6.3 KiB
| title | description | type | domain | tags | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Paper Dynasty Database API — Deployment Guide | Complete deployment guide for the PD Database API covering dev and prod release flows, CI/CD pipeline, Docker tag strategy, rollback procedures, and common gotchas. | guide | paper-dynasty |
|
Paper Dynasty Database API — Deployment Guide
Overview
The Database API (cal/paper-dynasty-database) uses a tag-driven CI/CD pipeline via Gitea Actions. Pushing a git tag triggers a Docker image build and push to Docker Hub. There are two deployment tracks:
| Track | Git Tag | Docker Tags | Environment | URL |
|---|---|---|---|---|
| Production | CalVer (e.g., 2026.3.6) |
:2026.3.6 + :production |
Prod | pd.manticorum.com |
| Dev | dev (force-updated) |
:dev |
Dev | pddev.manticorum.com |
Release Commands
Dev Deploy
# Via release script (preferred)
bash /mnt/NV2/Development/paper-dynasty/.claude/skills/release/release.sh database dev
# Manual
cd /mnt/NV2/Development/paper-dynasty/database
git checkout main && git pull --ff-only origin main
git tag -f dev && git push origin dev --force
The dev tag is force-updated every time — it always points to the latest commit you want to test. This is safe because the dev environment is not customer-facing.
Production Deploy
# Auto-increment version (preferred)
bash /mnt/NV2/Development/paper-dynasty/.claude/skills/release/release.sh database
# Explicit version
bash /mnt/NV2/Development/paper-dynasty/.claude/skills/release/release.sh database 2026.3.7
CalVer format: YYYY.M.BUILD (e.g., 2026.3.6). The script auto-increments BUILD if omitted.
CI/CD Pipeline
Workflow file: .gitea/workflows/build.yml
Trigger: Push of tags matching 20* (CalVer) or dev
Steps:
- Checkout code with full history
- Set up Docker Buildx with layer caching
- Login to Docker Hub (
manticorum67) - Build and push image with appropriate tags
- Rotate build cache
- Send Discord notification (success/failure)
Docker image: manticorum67/paper-dynasty-database
Build cache: Persistent volume pd-buildx-cache on the Gitea runner — significantly speeds up rebuilds since only changed layers are rebuilt.
Post-Build: Pulling the New Image
CI builds and pushes the image, but does not auto-deploy. You must pull and restart the container on the target host.
Dev Environment
ssh pd-database "cd /home/cal/container-data/dev-pd-database && docker compose pull && docker compose up -d"
- Host:
pd-database(SSH alias) - Container data:
/home/cal/container-data/dev-pd-database/ - Container:
dev_pd_database - Port: 813 (mapped to internal 8000)
- URL:
pddev.manticorum.com
Production Environment
ssh akamai "cd /root/container-data/paper-dynasty && docker compose pull && docker compose up -d"
- Host:
akamai(SSH alias) - Container:
pd_api - Port: 815 (mapped to internal 8000)
- URL:
pd.manticorum.com
Verification
Quick Curl Test
# Dev
curl -s https://pddev.manticorum.com/api/v2/awards?limit=2 | python3 -m json.tool
# Prod
curl -s https://pd.manticorum.com/api/v2/awards?limit=2 | python3 -m json.tool
Smoke Test
Use the /smoke-test skill:
/smoke-test dev
/smoke-test prod
Check Running Version
# Dev — check container image digest
ssh pd-database "docker inspect dev_pd_database --format '{{.Image}}'"
# Prod
ssh akamai "docker inspect pd_api --format '{{.Image}}'"
Rollback
Dev
Just re-tag dev to a known-good commit and force-push:
git tag -f dev <good-commit-sha>
git push origin dev --force
# Then pull on dev host
ssh pd-database "cd /home/cal/container-data/paper-dynasty-database && docker compose pull && docker compose up -d"
Production
Production images are tagged with both the CalVer version and :production. To roll back:
# On the prod host, pull a specific older version
ssh akamai "docker pull manticorum67/paper-dynasty-database:2026.3.5"
# Update compose to pin to that version, or just retag
ssh akamai "cd /root/container-data/paper-dynasty && docker compose up -d"
Common Gotchas
CalVer tag does NOT deploy to dev
CalVer tags (e.g., 2026.3.6) only build :version + :production Docker tags. The dev environment pulls :dev. You must push the dev git tag separately to deploy to dev.
CI build takes ~2-3 minutes
After pushing a tag, wait for CI to complete before pulling on the host. Check the Gitea Actions tab or wait for the Discord notification.
"dev" tag requires force-push
Since dev is reused, you must use git tag -f dev and git push origin dev --force. The release script handles this automatically.
Branch protection doesn't affect tags
Tags can be pushed by anyone with write access — no PR or review required. The review happens before merging to main; tagging is the release step.
scout_opportunities.py was base64-encoded
As of 2026-03-24, this file was stored as raw base64 in git. The total-count-pagination branch rewrote it to proper Python source. If you see base64 content in this file on older branches, that's expected — it's a legacy artifact.
Multiple PRs merging concurrently causes rebase races
When merging many PRs at once (e.g., batch pagination PRs), branch protection rules (block_on_outdated_branch + dismiss_stale_approvals) cause a merge storm. Each rebase invalidates the approval, requiring re-approve + re-merge. pd-ops agents handle this automatically but may take several attempts.
Environment Variables
| Var | Purpose |
|---|---|
API_TOKEN |
Bearer token for authenticated endpoints |
LOG_LEVEL |
Logging verbosity (default: INFO) |
DATABASE_TYPE |
postgresql |
POSTGRES_HOST |
Container name of PostgreSQL |
POSTGRES_DB |
Database name (pd_master) |
POSTGRES_USER |
DB username |
POSTGRES_PASSWORD |
DB password |
Topology Quick Reference
| Component | Host | Container | Port |
|---|---|---|---|
| Database API (prod) | ssh akamai |
pd_api |
815 |
| Database API (dev) | ssh pd-database |
dev_pd_database |
813 |
| PostgreSQL (prod) | ssh akamai |
pd_postgres |
5432 |
| PostgreSQL (dev) | ssh pd-database |
pd_postgres |
5432 |