Configuration specification

Single-Application Rule

In Dock, each dock.yaml defines exactly one application. You must provide either application.image (for published images) or application.source (for GitHub builds). Configuring both or neither will result in a validation error during dock validate.

1. Published Image Configuration

Use application.image when pulling an existing image from Docker Hub, GitHub Container Registry (GHCR), or any reachable registry.

name: hello-nginx

docker:
  enabled: true

application:
  image: nginx:alpine
  ports:
    - host: 8080
      container: 80
  healthcheck:
    type: http
    path: /
    port: 80

This maps http://localhost:8080 on your host machine to port 80 in the container and performs an HTTP check on path: / at container port 80.

2. GitHub Source Build Configuration

Use application.source with type: github to fetch a repository branch and build it locally with Docker:

name: hello-api

system:
  packages:
    - git

docker:
  enabled: true

application:
  source:
    type: github
    repository: owner/repository
    branch: main
  docker:
    dockerfile: Dockerfile
  ports:
    - host: 8000
      container: 8000
  healthcheck:
    type: http
    path: /
    port: 8000

GitHub Field Details

• type: Must be github.
• repository: Must be in owner/repository format (do not provide full https://github.com/... URLs).
• branch: The Git branch to fetch (e.g. main or v1.0).
• docker.dockerfile: Path to the Dockerfile relative to the repository root (e.g. Dockerfile).

3. Ports and Health Checks

Ports and health checks use explicit structured fields:

• ports: A list of mappings with host (integer) and container (integer).
• healthcheck.type: Health check protocol (currently http).
• healthcheck.path: HTTP endpoint path to verify (e.g. / or /health).
• healthcheck.port: Target port to query (e.g. 8080 or 8000).

4. System Packages (Host Prerequisites)

The optional system.packages section lists system packages needed on the host (such as git).

Scope & Design Decisions

Dock is intentionally single-application and local-first. Multi-container service definitions, hosted cloud deployments, and graphical UI dashboards are not part of the core feature set.