Docker Compose Deployment

PayWarden is designed to run as a single docker compose up command. This page covers deployment options from local dev to production.

Default stack

# docker-compose.yml
services:
  app:       # PayWarden gateway
  postgres:  # PostgreSQL 16
  redis:     # Redis 7

Quick start

git clone https://github.com/paywarden/paywarden
cd paywarden
cp .env.example .env
# Edit .env with your values
docker compose up -d

Check logs:

docker compose logs -f app

Environment file

The app container reads from .env in the project root. Never commit this file.

# .env.example shows all available variables
cat .env.example

Persistent data

By default, Docker volumes are used for PostgreSQL and Redis data:

volumes:
  postgres_data:
  redis_data:

Data persists across container restarts. To fully reset:

docker compose down -v   # ⚠️ deletes all data

Vault file

Your encrypted vault (vault.enc) is stored inside the container at /app/vault.enc by default. In production, mount it as a volume so it persists across image updates:

# docker-compose.yml (production override)
services:
  app:
    volumes:
      - ./vault.enc:/app/vault.enc

Or store the vault path outside the container:

VAULT_PATH=/data/paywarden/vault.enc

Production deployment

1. Use a reverse proxy

Run Nginx or Caddy in front of PayWarden:

# Nginx example
server {
    listen 443 ssl;
    server_name pay.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        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;
    }
}

With Caddy (automatic HTTPS):

pay.yourdomain.com {
    reverse_proxy localhost:3000
}

2. Use docker compose override

# docker-compose.prod.yml
services:
  app:
    restart: always
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=warn
    volumes:
      - ./vault.enc:/app/vault.enc

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

3. Resource limits

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M

Health check

curl http://localhost:3000/api/v1/health
# {"status":"ok","db":"ok","redis":"ok","uptime":3600}

Docker Compose includes a built-in health check that restarts the container if the health endpoint fails 3 times in a row.

Updating

docker compose pull
docker compose up -d

Database migrations run automatically on startup.

Backup

Back up these items regularly:

Item	Location	Priority
Mnemonic phrase	Written offline	🔴 Critical
VAULT_KEY	Password manager / HSM	🔴 Critical
PostgreSQL data	docker compose exec postgres pg_dump	🟡 Important
.env	Encrypted backup	🟡 Important

# PostgreSQL backup
docker compose exec postgres pg_dump -U postgres paywarden > backup_$(date +%Y%m%d).sql

# Restore
docker compose exec -T postgres psql -U postgres paywarden < backup_20250101.sql