Magent/PRODUCTION.md

Production

Magent runs as one combined frontend/API image: rephl3xnz/magent. The root Dockerfile is the supported build entry point. Source releases come from main; use prod-<short-commit> tags to identify an exact release.

Live deployment

• Host: GRZ-DKR01 (10.30.1.81).
• Container and Compose service: magent; Compose project: arrstack.
• Compose file: /home/zak/grizzlystack/arrstack/docker-compose.yml.
• Persistent data: /home/zak/grizzlystack/arrstack/magent/data → /app/data.
• Public URL: https://magent.grizzlyflix.co.nz.
• Caddy runs on AMS-CAD01 and proxies production to 10.30.1.81:3002.
• Beta remains separate on AMS-DEV01. Do not overwrite it or change its routes.

Release checklist

1. Run the backend tests and frontend production build. Review only the intended changes, then commit and push main. The repository workflow verifies main but intentionally does not deploy it; production changes require the remaining explicit release steps below.

2. Build from a clean source export using the root Dockerfile. Never include .env, databases or bootstrap credentials in the build context.

3. Publish rephl3xnz/magent:prod-<short-commit> and :latest to Docker Hub. Confirm their digests match.

4. Pull the new image before stopping production. Keep the old image under a rollback tag and back up the current Compose configuration.

5. Briefly stop only magent, then back up its complete data directory so SQLite and its WAL files are consistent. Protect backups: they contain private data.

6. Recreate only this service with docker compose -p arrstack -f /home/zak/grizzlystack/arrstack/docker-compose.yml up -d --no-deps --no-build magent. Confirm that Compose selects the intended image before running this command.

7. Check container health, the API /health endpoint, public login, the changed feature, database integrity and account counts. Do not trigger bulk permission changes, email sends or user imports as a deployment smoke test.

   Include browser-origin POST checks for both /api/auth/login and /api/auth/jellyfin/login: an empty form with Origin set to the public URL must reach input validation (422), while an unrelated origin must return 403. GET-only login/health checks do not detect origin-policy lockouts. Set CORS_ALLOW_ORIGIN to the exact public origin; the state-change guard also accepts the explicitly configured Hosting & proxy public URL, never a URL inferred from request Host or forwarded headers.

For rollback, select the saved image and recreate only Magent. Restore data only if needed; doing so can discard activity since the backup. Never restore a whole shared Compose or Caddy file without checking for unrelated changes first.

Build metadata

.build_number and backend/app/build_info.py currently hold the same legacy display build number as the frontend package files. .env should have exactly one BUILD_NUMBER assignment, not a history of previous releases. Docker release tags identify the deployed source commit independently of this display value.

scripts/process1.ps1 is a local development workflow: it updates metadata, runs tests, rebuilds local Docker, and can commit changes/send Discord messages. It is not the production deployment command. Its build-number helper can be tested safely with powershell -File scripts/test_env_build_number.ps1.

Fresh instances and historical notes

scripts/prepare_production_settings.py exports only allowlisted connection and SMTP settings for a fresh instance. Do not use it to replace a live database. docker-compose.production.yml is the separate fresh-instance template, not the live GRZ-DKR01 Compose file. docker-compose.hub.yml is the generic Docker Hub template; docker-compose.yml builds locally; docker-compose.beta.yml serves beta.

The temporary AMS-DEV01 setup and coming-soon cutover are retained under archived cutover notes.