Deploy Grimoire

This guide covers production deployment options for Grimoire.

Docker Compose

The recommended way to run Grimoire in production:

# docker-compose.yml
services:
  grimoire:
    build: .
    # Or use a pre-built image:
    # image: ghcr.io/lucabello/grimoire:latest
    ports:
      - "8000:8000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
      - ./data:/app/data:ro
      - grimoire-workspace:/app/workspace
      - ./state:/app/state
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
    restart: unless-stopped

volumes:
  grimoire-workspace:

Volume mounts

Mount	Purpose
config.yaml	Configuration file (read-only)
data/	Check and action definitions (read-only)
workspace/	Cloned repos (managed by Grimoire)
state/	Database and logs (persistent)

Plain Docker

docker build -t grimoire .

docker run -d \
  --name grimoire \
  -p 8000:8000 \
  -v ./config.yaml:/app/config.yaml:ro \
  -v ./data:/app/data:ro \
  -v grimoire-workspace:/app/workspace \
  --restart unless-stopped \
  grimoire

Reverse proxy

Grimoire listens on port 8000. Place it behind a reverse proxy for TLS termination.

Caddy

grimoire.example.com {
    reverse_proxy localhost:8000
}

Nginx

server {
    listen 443 ssl;
    server_name grimoire.example.com;

    ssl_certificate /etc/letsencrypt/live/grimoire.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/grimoire.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Health checks

Grimoire exposes a health endpoint at GET /health. The Docker image includes a built-in HEALTHCHECK that polls this endpoint every 30 seconds.

Security considerations

Grimoire executes arbitrary shell scripts

Checks and actions run user-provided bash scripts with full system access. Never expose Grimoire to untrusted users. Place it behind authentication if publicly accessible, and use a dedicated GitHub token with minimal permissions.

Resource usage

Grimoire is lightweight:

Resource	Usage
CPU	Minimal; spikes during check/action execution
Memory	~50–100 MB base; scales with tracked repos
Disk	Database grows slowly; workspace size depends on cloned repos
Network	GitHub API calls minimised via ETags and conditional requests