Spotig

A Docker container orchestration controller that uses Git as the source of truth. Define your containers, networks, and volumes as Docker Compose files in a Git repository, and Spotig continuously reconciles your Docker runtime to match.

Features

• Git-driven -- Clone/pull a Git repo containing Compose files; reconcile on every change
• Periodic polling & webhooks -- Detect changes via configurable poll intervals or Git push webhooks
• Stack model -- Each top-level directory = one stack (Compose project), with optional sub-stacks
• Secret resolution -- Replace secret:// references using 1Password Connect (or other backends)
• Prometheus metrics -- Reconcile duration, action counts, exposed on /metrics
• Event logging -- Structured JSON events to stdout or file
• Idempotent reconciliation -- Only applies the diff (create/update/delete) with retry support
• Multi-arch -- Builds for linux/amd64 and linux/arm64

Quick Start

# Build from source
make build

# Run with a config file
./spotig -config spotig.yaml

# Or run via Docker
docker run -v /var/run/docker.sock:/var/run/docker.sock \
  -v ./spotig.yaml:/etc/spotig/spotig.yaml \
  spotig:dev

Configuration

Create a spotig.yaml file (see examples/spotig.yaml for a full example):

git:
  url: git@github.com:your-org/your-infra.git
  branch: main
  poll_interval: 30s
  auth:
    ssh_key_path: /path/to/key

stacks:
  paths:
    - "*/docker-compose.yml"
    - "*/*.yml"

reconcile:
  debounce: 5s
  prune: true

See docs/config-schema.md for the full configuration reference.

How It Works

1. Spotig clones (or pulls) your Git repository
2. Discovers stacks by matching Compose files against glob patterns
3. Parses and merges Compose files, resolves .env inheritance and secrets
4. Reads current Docker state (containers, networks, volumes) for each stack
5. Computes a diff and applies changes in order: networks, volumes, then containers (creates); reverse order for deletes
6. Repeats on the configured poll interval or when triggered by a webhook

Repository Layout (Managed Repo)

your-infra-repo/
  stack-a/
    docker-compose.yml
    .env
  stack-b/
    docker-compose.yml
    substack-1/
      compose.yaml
      .env

Development

make build              # Build binary
make test               # Run unit tests
make integration        # Run integration tests (requires Docker)
make test-coverage      # Generate coverage report
make test-coverage-check # Verify coverage >= 90%
make docker-build       # Build Docker image (spotig:dev)

Requires Go 1.24+. See CLAUDE.md for detailed architecture and development guidance.

License

Apache License 2.0