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