familysync/docs/deployment.md

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).
• Pangolin/Newt tunnel configured to route an external HTTPS hostname to the Docker host on port 3000 (see Pangolin / Newt Tunnel).
• A .env file at the repo root with all required secrets (see Environment Setup).

---

Register the OIDC Client

Add the following client block to your Authelia configuration.yml under identity_providers.oidc.clients:

- 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:

# Authelia CLI — run on the host where Authelia is installed
authelia crypto hash generate pbkdf2 --variant sha512

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:

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

npx web-push generate-vapid-keys --json

See docs/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:

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

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:

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

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

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:

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:

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:

docker compose logs -f api
docker compose logs -f mariadb