ci(release): publish versioned artifacts

2026-08-01 15:02:31 -04:00
parent 326cc60688
commit 420389d601
14 changed files with 515 additions and 5 deletions
@@ -0,0 +1,67 @@
+# Releases and container deployment
+
+The public Gitea repository is hosted at `https://git.garvis.dev/dmg/minecraft-account-manager`. Public release assets, including the Velocity plugin JAR, can be downloaded without repository authentication.
+
+## Semantic versioning
+
+Releases are calculated from conventional commits on `main`:
+
+- `fix` creates a patch release.
+- `feat` creates a minor release.
+- `BREAKING CHANGE` or a breaking `!` creates a major release.
+- `chore(deps)` creates a patch release.
+- Other documentation, test, CI, and maintenance commits do not release by default.
+
+Release tags use `vMAJOR.MINOR.PATCH`. With no existing tags, the first release is `v1.0.0`. The Git tag is the authoritative platform version.
+
+## Required repository secrets
+
+Configure these under **Repository settings → Actions → Secrets** before the first push:
+
+| Secret | Purpose |
+| --- | --- |
+| `GITEA_TOKEN` | Checkout authentication, semantic-version tag publication, and Gitea release/asset creation. Use a token with write access to this repository. |
+| `REGISTRY_USERNAME` | Gitea container-registry username, normally `dmg`. |
+| `CONTAINER_REGISTRY_TOKEN` | Token used by Docker to publish packages for the `dmg` owner. |
+
+Never commit these values or place them in image build arguments.
+
+## Published artifacts
+
+Each release creates:
+
+- Gitea release asset `minecraft-account-manager-velocity-VERSION.jar`
+- `git.garvis.dev/dmg/minecraft-account-manager:VERSION`
+- `git.garvis.dev/dmg/minecraft-account-manager:latest`
+- `git.garvis.dev/dmg/minecraft-account-manager-migrate:VERSION`
+- `git.garvis.dev/dmg/minecraft-account-manager-migrate:latest`
+
+Use immutable version tags for deployments. `latest` is a convenience pointer to the newest release.
+
+## Database migration
+
+Run the migration image for the same version before starting or replacing the web container:
+
+```bash
+docker run --rm \
+  -e DATABASE_URL='postgresql://user:password@postgres:5432/minecraft_accounts' \
+  git.garvis.dev/dmg/minecraft-account-manager-migrate:1.0.0
+```
+
+The image runs `drizzle-kit migrate` against the versioned SQL files. It never runs `drizzle push`. Back up production PostgreSQL and test migrations against a representative staging database before deployment.
+
+## Web runtime
+
+The web image contains the Next.js standalone server and runs as an unprivileged user:
+
+```bash
+docker run --rm -p 3000:3000 \
+  --env-file /path/to/minecraft-account-manager.env \
+  git.garvis.dev/dmg/minecraft-account-manager:1.0.0
+```
+
+Provide all deployment settings described by [`.env.example`](../.env.example). Only set `TRUST_PROXY=true` behind a proxy that overwrites forwarding headers.
+
+## Velocity JAR
+
+Download the JAR from the matching public Gitea release, copy it to Velocity's `plugins/` directory, and retain the existing `plugins/minecraft-account-manager/config.properties` during upgrades.