ginnoir
13d94b3751
- rename Caddyfile.snippet → Caddyfile (maintainer's full production file) - restore Caddyfile.snippet as a minimal public reference (famapp blocks only) - add compose.example.yaml: standalone famapp + authentik template for new deployers; compose.yaml remains the maintainer's homelab monolith - update deploy/README.md: file table, setup steps referencing example files - apply-compose.ps1: point Caddy push at deploy/Caddyfile (not snippet)
60 lines
3.1 KiB
Markdown
60 lines
3.1 KiB
Markdown
# Deploying famapp
|
|
|
|
Trunk-based: `main` is always green. Production deploys only from version tags (`vX.Y.Z`). The dev-login flow is retained for local development behind a double gate (`NODE_ENV !== "production"` **and** `ENABLE_DEV_LOGIN=true`); a startup assertion in `src/lib/dev-login-config.ts` makes a misconfigured prod fail loud instead of silently exposing it.
|
|
|
|
## Files in this directory
|
|
|
|
| File | Purpose |
|
|
| ----------------------- | -------------------------------------------------------------------------- |
|
|
| `compose.example.yaml` | **Start here.** Standalone famapp + Authentik stack for new deployments. |
|
|
| `compose.yaml` | Maintainer's production compose (full homelab monolith — not a template). |
|
|
| `Caddyfile.snippet` | Reverse proxy blocks to add to your Caddyfile. |
|
|
| `Caddyfile.dev.snippet` | Dev machine proxy block (maintainer-specific). |
|
|
| `Caddyfile` | Maintainer's full production Caddyfile (not a template). |
|
|
| `authentik/README.md` | Authentik bootstrap guide. |
|
|
| `backups/` | Backup container scripts (used by `famapp-backup` in the example compose). |
|
|
|
|
## One-time host setup
|
|
|
|
1. Install Docker + Compose plugin on the host.
|
|
2. `git clone` this repo to e.g. `/srv/famapp`.
|
|
3. Copy `deploy/compose.example.yaml` → `/srv/famapp/deploy/compose.yaml`.
|
|
4. Copy `.env.production.example` → `/srv/famapp/deploy/.env` and fill in real values.
|
|
- `openssl rand -base64 32` for `AUTH_SECRET`.
|
|
- `openssl rand -base64 60` for `AUTHENTIK_SECRET_KEY`.
|
|
- `openssl rand -hex 64` for the MinIO passwords.
|
|
- `pnpm vapid:generate` (locally, from the repo) for the three VAPID lines.
|
|
5. Bootstrap Authentik per `deploy/authentik/README.md`. Save the OIDC client id/secret into `.env`.
|
|
6. Wire Caddy (or any reverse proxy) using `deploy/Caddyfile.snippet`.
|
|
|
|
## Cutting a release
|
|
|
|
```bash
|
|
# from your dev machine, on main, with a clean working tree
|
|
git tag v0.1.0
|
|
git push origin v0.1.0
|
|
```
|
|
|
|
`.github/workflows/release.yml` builds + pushes `ghcr.io/ginnoir/famapp:v0.1.0`, `:0.1`, and `:latest` to GHCR.
|
|
|
|
## Deploying a release on the host
|
|
|
|
```bash
|
|
cd /srv/famapp/deploy
|
|
# pin to the tag you just cut
|
|
sed -i 's|FAMAPP_IMAGE=.*|FAMAPP_IMAGE=ghcr.io/ginnoir/famapp:v0.1.0|' .env
|
|
docker compose pull famapp
|
|
docker compose up -d famapp
|
|
docker compose logs -f famapp # watch migrations + boot
|
|
```
|
|
|
|
The container's entrypoint runs `node scripts/migrate.mjs` before starting the server. To skip migrations on a given start (rare — e.g. emergency rollback to an older schema-compatible image), set `RUN_MIGRATIONS=false`.
|
|
|
|
## Rollback
|
|
|
|
Edit `.env` to point `FAMAPP_IMAGE` at the previous tag, then `docker compose up -d famapp`. If the rollback target predates a migration that's already applied, restore from backup (`deploy/backups/README.md`) before bringing the older image up.
|
|
|
|
## Pre-deploy checklist
|
|
|
|
Run [docs/tasks/09-pre-deploy-checklist.md](../docs/tasks/09-pre-deploy-checklist.md) before every deploy.
|