Docker Deployment

The Consul Guardian Docker image is built on Alpine Linux and includes Git and SSH client. It runs as a non-root guardian user.

Image

docker pull ghcr.io/consul-guardian/consul-guardian:latest

docker run

Watch only (no dashboard)

docker run -d \
  --name consul-guardian \
  -e CONSUL_GUARDIAN_CONSUL_ADDRESS=http://consul:8500 \
  -e CONSUL_GUARDIAN_CONSUL_TOKEN=your-acl-token \
  -v /data/consul-backup:/home/guardian/repo \
  consul-guardian watch \
    --prefix "config/,env/" \
    --git-repo /home/guardian/repo

Dashboard + watcher

docker run -d \
  --name consul-guardian \
  -e CONSUL_GUARDIAN_CONSUL_ADDRESS=http://consul:8500 \
  -e CONSUL_GUARDIAN_CONSUL_TOKEN=your-acl-token \
  -v /data/consul-backup:/home/guardian/repo \
  -p 9090:9090 \
  consul-guardian dashboard \
    --prefix "config/" \
    --git-repo /home/guardian/repo \
    --listen :9090

docker-compose

version: "3.8"

services:
  consul:
    image: hashicorp/consul:1.18
    command: agent -dev -client=0.0.0.0
    ports:
      - "8500:8500"

  guardian:
    image: ghcr.io/consul-guardian/consul-guardian:latest
    command:
      - dashboard
      - --prefix
      - "config/,env/,feature-flags/"
      - --git-repo
      - /home/guardian/repo
      - --listen
      - ":9090"
    environment:
      CONSUL_GUARDIAN_CONSUL_ADDRESS: "http://consul:8500"
      CONSUL_GUARDIAN_CONSUL_TOKEN: "${CONSUL_TOKEN}"
      CONSUL_GUARDIAN_LOGGING_LEVEL: "info"
      CONSUL_GUARDIAN_LOGGING_FORMAT: "json"
    ports:
      - "9090:9090"
    volumes:
      - guardian-data:/home/guardian/repo
    depends_on:
      - consul
    restart: unless-stopped

volumes:
  guardian-data:

Start with:

docker-compose up -d

Environment variables

All configuration values can be set via environment variables with the CONSUL_GUARDIAN_ prefix. Nested keys use underscores.

Environment Variable	Config Equivalent	Default
CONSUL_GUARDIAN_CONSUL_ADDRESS	consul.address	http://127.0.0.1:8500
CONSUL_GUARDIAN_CONSUL_TOKEN	consul.token	(empty)
CONSUL_GUARDIAN_CONSUL_DATACENTER	consul.datacenter	(auto-detect)
CONSUL_GUARDIAN_LOGGING_LEVEL	logging.level	info
CONSUL_GUARDIAN_LOGGING_FORMAT	logging.format	text
CONSUL_GUARDIAN_GIT_REPO_PATH	git.repo_path	./consul-backup
CONSUL_GUARDIAN_GIT_AUTO_PUSH	git.auto_push	false
CONSUL_GUARDIAN_WATCH_PREFIXES	watch.prefixes	config/
CONSUL_GUARDIAN_WATCH_POLL_INTERVAL	watch.poll_interval	5m
CONSUL_GUARDIAN_SNAPSHOT_STORAGE_TYPE	snapshot.storage.type	local
CONSUL_GUARDIAN_SNAPSHOT_STORAGE_PATH	snapshot.storage.path	./snapshots
CONSUL_GUARDIAN_SNAPSHOT_STORAGE_BUCKET	snapshot.storage.bucket	(empty)
CONSUL_GUARDIAN_SNAPSHOT_RETENTION_COUNT	snapshot.retention.count	30

Git SSH setup

To push backups to a remote Git repository from Docker, mount your SSH key:

docker run -d \
  -v /data/consul-backup:/home/guardian/repo \
  -v ~/.ssh/id_ed25519:/home/guardian/.ssh/id_ed25519:ro \
  -v ~/.ssh/known_hosts:/home/guardian/.ssh/known_hosts:ro \
  consul-guardian watch \
    --prefix "config/" \
    --git-repo /home/guardian/repo \
    --auto-push

Health check

Add a health check to verify Guardian can reach Consul:

services:
  guardian:
    # ...
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:9090/api/status"]
      interval: 30s
      timeout: 5s
      retries: 3