Getting started

Prerequisites

Dock (Deployment Operations and Configurations Kit) is a local-first CLI that orchestrates your machine's existing Docker daemon. Ensure you have:

• Python 3.10+: Required to run the CLI.
• Docker CLI & Docker Engine: Running locally (e.g. Docker Desktop, OrbStack, or Docker Engine on Linux).
• Git: Required when using the GitHub repository build workflow.

1. Install Dock

The PyPI distribution package is named dock-api. Installing it provides the dock command on your path:

$ python -m pip install dock-api
$ dock -v
Dock CLI v0.2.1

2. Create dock.yaml

Create a dock.yaml file in your project directory. In Dock, each configuration supports exactly one application using either a published image or a GitHub source.

Example A: Short-Lived Container (hello-world)

The standard hello-world image prints a greeting message and exits immediately. When inspecting it with Docker, status Exited (0) is expected because it is not a long-running web server.

name: hello-world

docker:
  enabled: true

application:
  image: hello-world:latest

Example B: Long-Running Web Server (hello-nginx)

For a service that stays online and serves requests, configure ports and an HTTP healthcheck. The following config maps host port 8080 to container port 80:

name: hello-nginx

docker:
  enabled: true

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

3. The Command Workflow

Dock separates validation, state inspection, change planning, and execution into explicit steps:

1. dock validate: Validates dock.yaml syntax and schema only. (Does not install or check host prerequisites).
2. dock plan: Concise list of pending prerequisite installations and provisioning actions (supports --json).
3. dock sync: Full read-only state comparison between configuration and local environment.
4. dock init: Applies the plan (installs packages, pulls/builds the image, starts the container, and verifies health checks).
5. dock status: Inspects host requirements, Docker daemon state, and project container status (supports --running and --stopped filters).

$ dock validate -c ./dock.yaml
✓ dock.yaml is valid

$ dock plan -c ./dock.yaml
Plan (hello-nginx):
  - Pull image: nginx:alpine
  - Port binding: 8080 -> 80
  - Healthcheck: http GET / on port 80

$ dock sync -c ./dock.yaml
(Read-only state comparison: 0 installed, 1 image pending, 1 container pending)

$ dock init -c ./dock.yaml
✓ Image pulled: nginx:alpine
✓ Container created and started
✓ Health check passed (http://localhost:8080/)

$ dock status --running -c ./dock.yaml
Project: hello-nginx
System Requirements: Satisfied
Docker: Running
Containers (Running):
  - dock-hello-nginx (running, port 8080 -> 80)

Passing Custom Config Paths

By default, Dock looks for dock.yaml in the current working directory. You can specify custom configuration file paths using positional arguments or flags:

• Positional path: dock init ./custom/dock.yaml
• Short flag -c: dock plan -c ./custom/dock.yaml
• Long flag --config: dock status --config ./custom/dock.yaml

Common Command Invocations

$ dock status -c ./dock.yaml
$ dock status --running -c ./dock.yaml
$ dock status --stopped -c ./dock.yaml
$ dock plan -c ./dock.yaml
$ dock sync -c ./dock.yaml
$ dock plan --json -c ./dock.yaml

Windows PowerShell Examples

On Windows PowerShell, use standard Windows path separators:

> dock validate -c .\custom\dock.yaml
> dock plan -c .\custom\dock.yaml
> dock sync --config .\custom\dock.yaml
> dock init -c .\custom\dock.yaml
> dock status --running -c .\custom\dock.yaml