# 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-bot:VERSION`
- `git.garvis.dev/dmg/minecraft-account-manager-migrate:VERSION`

Only immutable semantic-version tags are published. Mutable tags such as `latest` must never be used in deployments or release-asset URLs.

## Discord bot

Run exactly one bot replica with the same immutable release version as the web application. It requires `DATABASE_URL`, `APP_URL`, `DISCORD_BOT_TOKEN`, and `DISCORD_GUILD_ID`. Deploy slash commands separately with the release image when command definitions change.

## 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.

The release workflow passes the semantic version through Docker's `VERSION` build argument, and the final image embeds it as `APP_VERSION`. `GET /healthz` reports this immutable image version with readiness, for example `{"status":"ok","version":"1.19.0"}`. Manual builds that omit the build argument report `development`.

## 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.