Bootstrap configuration

deeplo has a two-layer configuration model:

The two layers are strictly separated. Managed config contains only structural deployment config — no paths, credentials, or runtime settings.

All bootstrap env vars use the DEEPLO_ prefix. Defaults prefer .yml, but explicit .yaml paths still work when you set them directly.

Environment variables

Config source

Data and SSH

HTTP and admin

Concurrency

Logging

GitHub integration

Local config mode

If DEEPLO_CONFIG_REPO_URL is unset, deeplo reads the managed YAML config from DEEPLO_CONFIG_FILE (default /etc/deeplo/config.yml).

# docker-compose.yml
services:
  deeplo:
    image: ghcr.io/jancernik/deeplo:latest
    environment:
      DEEPLO_DATA_DIR: /var/lib/deeplo
      DEEPLO_SSH_KEY_FILE: /run/secrets/deploy_key
      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

Advanced: local config file watching (DEEPLO_CONFIG_WATCH)

DEEPLO_CONFIG_WATCH is an advanced convenience feature for local config mode. It tells deeplo to watch the managed config file on disk and reload it when the file changes instead of requiring a daemon restart after config edits.

Set DEEPLO_CONFIG_WATCH=true to enable it.

When a change is detected and the new config is valid:

1. The in-memory config is replaced atomically.
2. The poller is restarted with the updated repo list and intervals.
3. Invalid configs are rejected and logged; the current config remains active.

environment:
  DEEPLO_CONFIG_WATCH: "true"

This is useful in development or when the config file is managed by a configuration management tool (Ansible, Puppet, etc.) that writes files directly to the host.

It is not the primary deployment path. If you just want a straightforward setup, mount a local config file and restart the daemon when you change it.

Git config mode

When DEEPLO_CONFIG_REPO_URL is set, deeplo fetches the managed config YAML from a git repository on startup. This is useful when you want the deployment config itself to be version-controlled and managed like any other file in a repo.

# docker-compose.yml
services:
  deeplo:
    image: ghcr.io/jancernik/deeplo:latest
    environment:
      DEEPLO_CONFIG_REPO_URL: git@github.com:yourorg/deeplo-config.git
      DEEPLO_CONFIG_REPO_BRANCH: main
      DEEPLO_CONFIG_REPO_FILE: config.yml
      DEEPLO_CONFIG_REPO_MODE: hybrid
      DEEPLO_DATA_DIR: /var/lib/deeplo
      DEEPLO_SSH_KEY_FILE: /run/secrets/deploy_key
      DEEPLO_GITHUB_WEBHOOK_SECRET_FILE: /run/secrets/github_webhook_secret
    volumes:
      - ./data:/var/lib/deeplo
    secrets:
      - deploy_key
      - github_webhook_secret

What happens on startup (git mode)

1. ls-remote is run against DEEPLO_CONFIG_REPO_URL to get the branch tip SHA.
2. The config repo is cloned as a bare mirror into DEEPLO_DATA_DIR/config/repos/ (or fetched if already present).
3. The config file at DEEPLO_CONFIG_REPO_FILE is read from that exact commit.
4. The config is parsed and validated.
5. If valid, it is written to the last-known-good cache at DEEPLO_DATA_DIR/config/current.yml.

Automatic reload (git mode)

After startup, a config watcher detects changes to the config repo and reloads automatically. How it detects changes is controlled by DEEPLO_CONFIG_REPO_MODE:

When a new commit is detected and the updated config is valid:

1. The in-memory config is replaced atomically — all subsequent deploys use the new values.
2. The poller is restarted so new repos, intervals, and trigger modes take effect immediately.
3. The webhook route (/webhooks/github) always reads the current config, so newly added webhook-mode repos are handled without a daemon restart.

Changing a repo's trigger_mode or poll_interval reloads the runtime trigger behavior only. It does not by itself redeploy all projects. When a repo is switched from webhook-only to poll or hybrid mode, deeplo seeds the current branch tip as the poll baseline so the reload does not create an artificial first-poll deploy storm.

Invalid configs are rejected and logged; the current config remains active.

Required env vars for git mode

DEEPLO_SSH_KNOWN_HOSTS defaults to DEEPLO_DATA_DIR/known_hosts. With DEEPLO_SSH_HOST_KEY_POLICY=accept-new (default), host keys are accepted automatically on first connection and stored there.

Last-known-good cache (git mode)

When DEEPLO_CONFIG_REPO_URL is set, deeplo maintains a last-known-good cache:

DEEPLO_DATA_DIR/config/
  current.yml     validated managed config from last successful fetch
  meta.json       source URL, branch, commit SHA, fetch timestamp
  repos/          bare git mirror of the config repo

Bad config pushes cannot take down a running daemon — the previous valid config remains active until a valid one is pushed.

Shared SSH key

deeplo uses DEEPLO_SSH_KEY_FILE for both:

• fetching the managed config repo in git mode
• fetching watched repos
• deploying to target hosts over SSH

If you need different credentials, that is outside the current product scope. The bootstrap layer keeps the SSH auth story intentionally simple.