Run with Docker

Run deeplo as a Docker Compose service — setup, configuration, and operational notes.

deeplo can run as a Docker Compose service. This is a supported alternative to the systemd installation. Both approaches use the same binary and behave identically; the difference is only in how the daemon is managed and how configuration is supplied.

Use Docker if:

You already run infrastructure via Docker Compose on the host
You want the daemon isolated in a container with explicit volume mounts
You're evaluating deeplo before committing to a permanent install

Use systemd if:

You want the daemon managed by the OS process supervisor
You prefer native binary installs
You want deeplo status, deeplo runs, and deeplo health to work from any shell without docker exec

Directory layout

/your/deploy-dir/
  docker-compose.yml
  config.yml
  data/                 ← created automatically on first run
  secrets/
    deploy_key
    deploy_key.pub
    github_webhook_secret   ← optional

docker-compose.yml

services:
  deeplo:
    image: ghcr.io/jancernik/deeplo:latest
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      DEEPLO_DATA_DIR: /var/lib/deeplo
      DEEPLO_SSH_KEY_FILE: /run/secrets/deploy_key
      DEEPLO_SSH_USER: deploy
      DEEPLO_WEBHOOK_PORT: 8080
      DEEPLO_GITHUB_WEBHOOK_SECRET_FILE: /run/secrets/github_webhook_secret
    volumes:
      - ./config.yml:/etc/deeplo/config.yml:ro
      - ./data:/var/lib/deeplo
    secrets:
      - deploy_key
      - github_webhook_secret

secrets:
  deploy_key:
    file: ./secrets/deploy_key
  github_webhook_secret:
    file: ./secrets/github_webhook_secret

The container's default command is deeplo daemon. You do not need to set a command or entrypoint.

Setup steps

1. Create a deploy key

mkdir -p secrets
ssh-keygen -t ed25519 -f secrets/deploy_key -N ""
# Copy secrets/deploy_key.pub to ~/.ssh/authorized_keys on each deploy target

2. Create a webhook secret (skip if using poll-only mode)

openssl rand -hex 32 > secrets/github_webhook_secret

3. Create config.yml

version: 1

hosts:
  - name: web-1
    address: 10.0.0.10
    remote_base_dir: /srv/apps

repos:
  - name: myapp
    url: git@github.com:yourorg/myapp.git
    branch: main
    trigger_mode: hybrid
    poll_interval: 5m

projects:
  - name: myapp
    repo: myapp
    repo_subdir: deploy
    targets:
      - web-1

4. Validate the config

deeplo check --config config.yml

Or without a local deeplo binary:

docker run --rm \
  -v ./config.yml:/etc/deeplo/config.yml:ro \
  ghcr.io/jancernik/deeplo:latest \
  check --config /etc/deeplo/config.yml

5. Start the daemon

docker compose up -d
docker compose logs -f

Expected startup output:

deeplo daemon starting  version=v0.1.0  config_source=local  webhook_port=8080
webhook handler registered  path=/webhooks/github
admin socket listening  path=/run/deeplo/deeplo.sock
listening  addr=:8080

CLI access in Docker

The deeplo binary in the container works for all CLI commands. Run them via docker exec:

docker exec deeplo deeplo health
docker exec deeplo deeplo status
docker exec deeplo deeplo runs
docker exec deeplo deeplo reload

Or with Docker Compose:

docker compose exec deeplo deeplo health
docker compose exec deeplo deeplo reload

deeplo service, deeplo env, and systemd-specific doctor checks are not supported inside the container — they will fail with a clear error. Use Docker's native tooling for container lifecycle management.

Operational commands

# Watch logs
docker compose logs -f

# Restart (picks up env changes)
docker compose restart deeplo

# Reload config without restart
docker compose exec deeplo deeplo reload

# Check health
docker compose exec deeplo deeplo health

# View deployment state
docker compose exec deeplo deeplo status

# View recent runs
docker compose exec deeplo deeplo runs

# Update to a new image
docker compose pull deeplo
docker compose up -d deeplo

Environment variable reference

All deeplo configuration is via environment variables. Set them in the environment: block of your Compose service. See Bootstrap config for the full list.

Key variables for a Docker deployment:

Variable	Example	Notes
`DEEPLO_DATA_DIR`	`/var/lib/deeplo`	Map to a named volume or bind mount
`DEEPLO_SSH_KEY_FILE`	`/run/secrets/deploy_key`	Mount as a Docker secret
`DEEPLO_SSH_USER`	`deploy`	Default SSH user on target hosts
`DEEPLO_WEBHOOK_PORT`	`8080`	Must match the published port
`DEEPLO_GITHUB_WEBHOOK_SECRET_FILE`	`/run/secrets/github_webhook_secret`	Omit if poll-only
`DEEPLO_LOG_FORMAT`	`json`	Recommended for Docker log drivers