Lucas Berger
982438dc10
Mechanical reformat — no logic changes. 398 files changed, 19125 insertions(+), 16457 deletions(-). Prettier 3.8.4 with .prettierrc (singleQuote:true, semi:true, tabWidth:2, trailingComma:all, printWidth:100). Isolated per D-13-08 for reviewability.
237 lines
9.2 KiB
Markdown
237 lines
9.2 KiB
Markdown
<!-- generated-by: gsd-doc-writer -->
|
|
|
|
# FamilySync — Deployment Guide
|
|
|
|
Self-hosted Docker deployment on Unraid behind Authelia OIDC and a Pangolin/Newt outbound tunnel. The API serves the compiled React PWA as static files on a single port (3000), so only one route needs to be exposed through the tunnel.
|
|
|
|
---
|
|
|
|
## Deployment Targets
|
|
|
|
| Target | Config file |
|
|
| ----------------------------- | --------------------------------------------------------- |
|
|
| Docker Compose (production) | `docker-compose.yml` |
|
|
| Docker Compose (dev override) | `docker-compose.dev.yml` |
|
|
| Container image | `apps/api/Dockerfile` (multi-stage, built from repo root) |
|
|
|
|
The production compose file brings up three services:
|
|
|
|
| Service | Image | Purpose |
|
|
| --------- | ---------------------------------------------------- | ---------------------------------------------------------- |
|
|
| `api` | Built from `apps/api/Dockerfile` target `production` | Hono API + compiled React PWA, listens on port 3000 |
|
|
| `mariadb` | `mariadb:11` | Persistent MariaDB database |
|
|
| `redis` | `redis:7-alpine` | Present for live list sync (pub/sub); unused until Phase 4 |
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- Docker and Docker Compose available on the Unraid host.
|
|
- Authelia already deployed with a FamilySync OIDC client registered (see [Register the OIDC Client](#register-the-oidc-client)).
|
|
- Pangolin/Newt tunnel configured to route an external HTTPS hostname to the Docker host on port 3000 (see [Pangolin / Newt Tunnel](#pangolin--newt-tunnel)).
|
|
- A `.env` file at the repo root with all required secrets (see [Environment Setup](#environment-setup)).
|
|
|
|
---
|
|
|
|
## Register the OIDC Client
|
|
|
|
Add the following client block to your Authelia `configuration.yml` under `identity_providers.oidc.clients`:
|
|
|
|
```yaml
|
|
- client_id: familysync
|
|
client_name: FamilySync
|
|
client_secret: '<pbkdf2-hash-of-your-plaintext-secret>'
|
|
public: false
|
|
authorization_policy: one_factor
|
|
redirect_uris:
|
|
- https://familysync.DOMAIN/callback # replace DOMAIN with your actual domain
|
|
scopes:
|
|
- openid
|
|
- profile
|
|
- email
|
|
- offline_access
|
|
response_types:
|
|
- code
|
|
grant_types:
|
|
- authorization_code
|
|
- refresh_token
|
|
require_pkce: true
|
|
pkce_challenge_method: S256
|
|
token_endpoint_auth_method: client_secret_basic
|
|
userinfo_signed_response_alg: none
|
|
```
|
|
|
|
These parameters are fixed — do not change `response_types`, `grant_types`, `require_pkce`, `pkce_challenge_method`, or `token_endpoint_auth_method`.
|
|
|
|
To generate the pbkdf2 hash from your chosen plaintext secret:
|
|
|
|
```bash
|
|
# Authelia CLI — run on the host where Authelia is installed
|
|
authelia crypto hash generate pbkdf2 --variant sha512
|
|
```
|
|
|
|
<!-- VERIFY: Authelia CLI command syntax may vary by version; verify against your installed Authelia release -->
|
|
|
|
Store the **plaintext** secret in `.env` as `OIDC_CLIENT_SECRET`. Never use the hash in `.env`.
|
|
|
|
---
|
|
|
|
## Environment Setup
|
|
|
|
Copy `.env.example` to `.env` at the repo root and fill in every value. The file is gitignored and must never be committed.
|
|
|
|
Minimum production `.env`:
|
|
|
|
```dotenv
|
|
# Database
|
|
DB_PASSWORD=<strong-password>
|
|
DB_ROOT_PASSWORD=<strong-root-password>
|
|
|
|
# OIDC
|
|
OIDC_AUTH_SECRET=<run: openssl rand -base64 32>
|
|
OIDC_ISSUER=https://auth.DOMAIN
|
|
OIDC_CLIENT_SECRET=<plaintext-secret-matching-authelia-hash>
|
|
OIDC_REDIRECT_URI=https://familysync.DOMAIN/callback
|
|
OIDC_AUTH_EXTERNAL_URL=https://familysync.DOMAIN
|
|
|
|
# Broker (Fastmail app-password encryption)
|
|
APP_PASSWORD_ENCRYPTION_KEY=<run: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))">
|
|
|
|
# Web Push (VAPID) — optional but required for push notifications
|
|
VAPID_PUBLIC_KEY=<base64-public-key>
|
|
VAPID_PRIVATE_KEY=<base64-private-key>
|
|
VAPID_SUBJECT=mailto:admin@example.com
|
|
```
|
|
|
|
`OIDC_CLIENT_ID` defaults to `familysync` and does not need to be set unless you registered a different ID in Authelia.
|
|
|
|
`OIDC_SCOPES` defaults to `openid profile email offline_access`. Do not add scopes that are not configured on the Authelia client.
|
|
|
|
**`DEV_AUTH_BYPASS` must NOT appear in the production `.env` or `docker-compose.yml`.** The API enforces this in code: when `NODE_ENV=production` the bypass is unconditionally disabled regardless of other variables, but omitting it entirely is the correct posture.
|
|
|
|
Generate VAPID keys:
|
|
|
|
```bash
|
|
npx web-push generate-vapid-keys --json
|
|
```
|
|
|
|
See [docs/CONFIGURATION.md](CONFIGURATION.md) for the full variable reference including optional variables and defaults.
|
|
|
|
---
|
|
|
|
## Apply Database Migrations
|
|
|
|
The production image does **not** auto-migrate on startup. Migrations must be applied manually before the first container start and again after any schema change.
|
|
|
|
Migrations are run with `drizzle-kit`, which is a **devDependency**. The production image is built with `pnpm install --prod` (see `apps/api/Dockerfile`), so `drizzle-kit` is **not** present inside the running `api` container — you cannot migrate by exec-ing into it. Instead, run migrations from a host that has the full (dev) dependencies and can reach MariaDB.
|
|
|
|
The production `docker-compose.yml` does not expose the MariaDB port externally, so bring the database up with the dev compose override (which binds port 3306), apply the migrations from the host, then start the rest of the stack:
|
|
|
|
```bash
|
|
# 1. Bring up only MariaDB with the host port exposed
|
|
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d mariadb
|
|
|
|
# 2. Wait for it to be healthy
|
|
docker compose ps
|
|
|
|
# 3. Apply migrations from the host (requires dev deps installed: `pnpm install`)
|
|
DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=familysync DB_NAME=familysync DB_PASSWORD=<value> \
|
|
pnpm --filter @familysync/api db:migrate
|
|
|
|
# 4. Start the full stack
|
|
docker compose up -d
|
|
```
|
|
|
|
**Never use `drizzle-kit push` against this MariaDB.** The `mysql` dialect mis-reads MariaDB 11.x schema metadata and schedules false destructive operations (table truncation). Always use `db:generate` + `db:migrate`.
|
|
|
|
---
|
|
|
|
## Pangolin / Newt Tunnel
|
|
|
|
The app is exposed to the public internet via an outbound Pangolin/Newt tunnel — no inbound ports are opened on the Unraid host.
|
|
|
|
<!-- VERIFY: Pangolin/Newt route configuration steps depend on your Pangolin dashboard and site-specific settings -->
|
|
|
|
Configure the Pangolin route to forward HTTPS traffic for `https://familysync.DOMAIN` to `http://<docker-host-ip>:3000`. The `api` service in `docker-compose.yml` publishes port 3000 on the host:
|
|
|
|
```yaml
|
|
ports:
|
|
- '3000:3000'
|
|
```
|
|
|
|
Ensure `OIDC_AUTH_EXTERNAL_URL` and `OIDC_REDIRECT_URI` in `.env` match the public hostname Pangolin exposes. Without `OIDC_AUTH_EXTERNAL_URL`, the OIDC middleware builds the callback URI from the internal container hostname, which will not match the URI registered in Authelia and will break the login flow.
|
|
|
|
---
|
|
|
|
## Build and Start
|
|
|
|
```bash
|
|
# From the repo root — builds both the API and the React PWA into one image
|
|
docker compose build
|
|
|
|
# Start all services
|
|
docker compose up -d
|
|
```
|
|
|
|
The Dockerfile uses a multi-stage build:
|
|
|
|
1. `builder` — compiles the TypeScript API (`pnpm --filter @familysync/api build`).
|
|
2. `pwa-builder` — builds the React PWA with Vite (`pnpm --filter @familysync/pwa build`).
|
|
3. `production` — installs production-only dependencies, copies the compiled API and the built PWA into `./public`. The API serves the PWA at `/` via `serveStatic`.
|
|
|
|
Both `builder` and `pwa-builder` stages run in parallel under BuildKit.
|
|
|
|
Rebuild after any source change:
|
|
|
|
```bash
|
|
docker compose build api && docker compose up -d api
|
|
```
|
|
|
|
The `api` service waits for the `mariadb` healthcheck to pass before starting (`depends_on: condition: service_healthy`).
|
|
|
|
---
|
|
|
|
## Health Check
|
|
|
|
The `/health` endpoint is unauthenticated and confirms a live database connection:
|
|
|
|
```bash
|
|
curl https://familysync.DOMAIN/health
|
|
# {"ok":true,"db":"up"}
|
|
```
|
|
|
|
A `503` response (`{"ok":false,"db":"down"}`) means the API cannot reach MariaDB. Check `docker compose logs api` and `docker compose logs mariadb`.
|
|
|
|
---
|
|
|
|
## Rollback
|
|
|
|
There is no automated rollback pipeline. To revert to a previous build:
|
|
|
|
1. Identify the prior working Git commit.
|
|
2. Stop the API: `docker compose stop api`.
|
|
3. Rebuild from the target commit: `git checkout <commit> && docker compose build api`.
|
|
4. Start: `docker compose up -d api`.
|
|
5. If the rollback crosses a schema migration boundary, restore the MariaDB volume from a backup — schema downgrades are not supported by Drizzle Kit's migrate command.
|
|
|
|
Take a MariaDB dump before every deployment that includes a migration:
|
|
|
|
```bash
|
|
docker compose exec mariadb mariadb-dump -u root -p familysync > backup-$(date +%Y%m%d).sql
|
|
```
|
|
|
|
---
|
|
|
|
## Monitoring
|
|
|
|
No monitoring agent is configured in the repository. The `/health` endpoint is available for uptime monitoring tools.
|
|
|
|
Application logs are written to stdout/stderr and captured by Docker:
|
|
|
|
```bash
|
|
docker compose logs -f api
|
|
docker compose logs -f mariadb
|
|
```
|
|
|
|
<!-- VERIFY: No Sentry, Datadog, or OpenTelemetry dependency is present in package.json — confirm whether any external monitoring is wired at the infrastructure level -->
|