193 lines
6.3 KiB
Markdown
193 lines
6.3 KiB
Markdown
---
|
|
title: "Paper Dynasty Database API — Deployment Guide"
|
|
description: "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."
|
|
type: guide
|
|
domain: paper-dynasty
|
|
tags: [paper-dynasty, deployment, docker, gitea, ci-cd, database, release]
|
|
---
|
|
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:**
|
|
1. Checkout code with full history
|
|
2. Set up Docker Buildx with layer caching
|
|
3. Login to Docker Hub (`manticorum67`)
|
|
4. Build and push image with appropriate tags
|
|
5. Rotate build cache
|
|
6. 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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 |
|