Getting Started

This guide gets Holden running on your server. Once set up, you’ll add apps via the Deploying Apps guide.

Prerequisites

1. Docker installed and running
2. Traefik running on a network called traefik

Tip

Don’t have Traefik yet? See traefik.io/getting-started or the examples folder for a complete docker-compose.yml with Traefik included.

1. Run Holden

docker-compose

docker-compose.yml

services:
  holden:
    image: benjick/holden:latest
    container_name: holden
    restart: unless-stopped
    ports:
      - "127.0.0.1:6021:6021"  # Internal API (CLI)
    labels:
      - "holden.orchestrator=true"  # Required for self-updates
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /appdata:/appdata
      - /backups:/backups
      - ./data:/data
    environment:
      HOLDEN_BASE_DATA_DIR: /appdata
      HOLDEN_TRAEFIK_NETWORK: traefik
      HOLDEN_PUBLIC_DOMAIN: holden.example.com
      HOLDEN_WEBHOOK_SECRET: change-me-to-something-random
      HOLDEN_BACKUP_DIR: /backups
      GITHUB_USERNAME: your-username  # Optional, for GHCR
      GITHUB_PAT: ghp_xxxx  # Optional, for private repos/GHCR
    networks:
      - traefik

networks:
  traefik:
    external: true

docker run

mkdir -p data
docker run -d \
  --name holden \
  --network traefik \
  --label holden.orchestrator=true \
  -p 127.0.0.1:6021:6021 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /appdata:/appdata \
  -v /backups:/backups \
  -v ./data:/data \
  -e HOLDEN_BASE_DATA_DIR=/appdata \
  -e HOLDEN_TRAEFIK_NETWORK=traefik \
  -e HOLDEN_PUBLIC_DOMAIN=holden.example.com \
  -e HOLDEN_WEBHOOK_SECRET=change-me-to-something-random \
  -e HOLDEN_BACKUP_DIR=/backups \
  benjick/holden:latest

Ports:

• 6021 - Internal API for CLI. Bound to localhost only for security. Webhooks (6020) are accessed via Traefik on the Docker network.

Volumes:

• /var/run/docker.sock - Docker socket. Lets Holden manage containers on your host.
• /appdata:/appdata - Persistent storage for your apps. Database files, uploads, etc. live here. The host and container paths must be identical — Holden creates sibling containers via the Docker socket, so volume paths it writes are resolved by the Docker daemon against the host filesystem, not from inside Holden’s container.
• /backups:/backups - Backup snapshots created during the maintenance window. Containers are stopped before backup, so files are never copied mid-write.
• /data - Holden’s persistent state: app registrations (apps.yml), encryption keys, and password seed. Generated automatically on first run.

Note

On first run, Holden generates a password seed and an age keypair in /data. Don’t delete them or your database passwords will change. See Security for details.

2. Add Your First App

Register an app using the CLI or the internal API:

holden app add my-app --repo https://github.com/you/my-app

See Deploying Apps for the full guide.

Verify It’s Running

Check the logs:

docker logs holden

You should see Holden start up and begin reconciling any registered apps.

Next: Deploy Your First App

Deploying Apps Add your first app to Holden