Hogwarts House Cup

Go BFF API + Astro frontend for house cup scores. Edge nginx 8087 (dev); API 5087; Astro 4087; Postgres 6087. Production: https://cup.arcanedemesne.com. Stage: https://stage.cup.arcanedemesne.com.

Port matrix: Gateway/PORT_MATRIX.md

Compose

Requires gateway-hub (edge only) and authentik-net (API OIDC backchannel) — create once from Gateway. Never put api/app on gateway-hub.

cp .env.example .env
make up
make migrate-up

Production (tier-2 ports 8287/6287):

cp .env.example .env.prod
make up-prod
make migrate-up-prod

Stage (tier-1 ports 8187/6187):

cp .env.stage.example .env.stage
make up-stage
make migrate-up-stage

Env files

File	Use
.env.example	Dev (cup-dev, tier-0)
.env	make up
.env.stage.example	Stage template
.env.stage	make up-stage
.env.prod	make up-prod

Local split-port

Process	Directory	Env	URL
Go API	backend/	.env.local	http://localhost:5087
Astro	frontend/cup/	src/.env.development.local	http://localhost:4087

# Terminal 1 — backend/
cp .env.example .env.local
make run

# Terminal 2 — frontend/cup/
bun install && bun dev

Auth

OIDC via Packages/authentication. Cookie per tier: cup-auth-dev / -stage / -prod. Groups: homelab-users / homelab-admins. See docs/SSO.md.

Migrations

Tier	Postgres (host)	Migrate
dev	6087	make migrate-up
stage	6187	make migrate-up-stage
prod	6287	make migrate-up-prod

Reload edge after backend recreate: make proxy-reload-dev, proxy-reload-stage, or proxy-reload-prod.

Stage deploy: .forgejo/workflows/deploy-stage.yaml.

Tests

make test
# optional frontend:
make test-frontend

Routes

Page	Path
Hero	/
House Cup board	/house-cup (session required)

API: GET /api/v1/health, GET /api/v1/houses, PATCH /api/v1/houses/{id} body { "score": <int> }.