Deployment¶

Verified against docker-compose.yml, .env.production.example, and deploy-production.ps1 on 2026-05-07.

Deployment model¶

GitPulse runs as a Docker Compose stack:

• postgres
• redis
• api
• worker
• scheduler
• caddy

Optional (--profile monitoring):

• prometheus
• grafana
• jaeger

flowchart TB
    Internet["Internet"] --> Caddy["Caddy"]
    Caddy --> API["FastAPI API"]
    Caddy -->|"/docs/"| Docs["MkDocs (nginx)"]
    API --> Postgres[("PostgreSQL")]
    API --> Redis[("Redis")]
    Worker["Worker ×4"] --> Redis
    Worker --> Postgres
    Scheduler["rq-scheduler"] --> Redis

Prerequisites¶

• Docker 24+
• Docker Compose 2.20+
• .env.production based on .env.production.example
• GitLab OAuth application (for dashboard login)

Required configuration¶

At minimum, set:

• DATABASE_URL
• POSTGRES_PASSWORD
• REDIS_PASSWORD (the APP_ENV=production validator refuses to start when REDIS_URL lacks a password segment)
• SECRET_KEY
• TEACHER_API_TOKEN
• GITLAB_OAUTH_CLIENT_ID
• GITLAB_OAUTH_CLIENT_SECRET
• GITLAB_API_TOKEN (or legacy alias GITLAB_TOKEN)
• DOMAIN

Quick production deploy (PowerShell)¶

1
2
3
4

cp .env.production.example .env.production
# fill values

.\deploy-production.ps1 -Build -Migrate

With monitoring profile:

1

.\deploy-production.ps1 -Monitoring

Manual deploy (cross-platform)¶

1. Migrations¶

1

docker compose --env-file .env.production --profile migrate run --rm migrate

2. Start stack¶

1

docker compose --env-file .env.production up -d

3. Monitoring (optional)¶

1

docker compose --env-file .env.production --profile monitoring up -d

Post-deploy verification¶

1
2
3

curl http://localhost:8000/health
curl http://localhost:8000/health/ready
curl http://localhost:8000/metrics

UI endpoints:

• dashboard: http://localhost/dashboard/
• docs (production, via Caddy): http://localhost/docs/
• docs (fallback, via FastAPI): http://localhost:8000/project-docs/

Service ports¶

Rollback¶

1
2
3

docker compose --env-file .env.production down
# or with monitoring profile
# docker compose --env-file .env.production --profile monitoring down

Related docs¶

• Monitoring
• Updates
• Backup