familysync/docs/GETTING-STARTED.md

FamilySync — Getting Started

This guide walks from a fresh clone to a running local development environment.

---

Prerequisites

Requirement	Version	Notes
Node.js	22 LTS	Matches the node:22-alpine base in apps/api/Dockerfile
pnpm	11.5.1	Pinned in package.json packageManager field; enable via corepack enable pnpm
Docker + Docker Compose	Any recent version	Used to run MariaDB locally

Node version management: If you use nvm or fnm, install Node 22 LTS and set it as the default before continuing. There is no .nvmrc in the repo; the target version comes from the Dockerfile.

---

Installation

1. Clone the repository

git clone <repository-url>
cd familysync

2. Enable pnpm via corepack

corepack enable pnpm

3. Install dependencies

pnpm install

4. Copy the environment file

cp .env.example .env

Open .env and fill in the required values. See docs/CONFIGURATION.md for the full variable reference. At minimum for local development you need:

• DB_PASSWORD and DB_ROOT_PASSWORD — pick any local passwords

• APP_PASSWORD_ENCRYPTION_KEY, SESSION_SECRET, LOCAL_SESSION_SECRET, and VAPID keys — generate all at once with:

  pnpm generate-secrets
  

  Paste the output into your .env. Alternatively, generate APP_PASSWORD_ENCRYPTION_KEY alone with:

  node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
  

• DEV_AUTH_BYPASS=true — bypasses the live Authelia OIDC flow for local dev. When this is set, LOCAL_SESSION_SECRET is not required at startup (bypass mode skips the local-auth JWT path entirely).

• DB_HOST=localhost — the dev Docker Compose exposes MariaDB on the host at localhost:3306

Note: If you run without DEV_AUTH_BYPASS=true (local-auth mode), LOCAL_SESSION_SECRET must be set to a value of at least 32 characters. The API will refuse to start otherwise. pnpm generate-secrets always produces a valid value.

---

First Run

5. Start the database services

docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d mariadb

This starts MariaDB (bound to localhost:3306) using the dev override. Wait for MariaDB to pass its health check before proceeding.

6. Run database migrations

set -a; source .env; set +a
pnpm --filter @familysync/api db:migrate

This runs drizzle-kit migrate against your local MariaDB using the credentials from .env. Do not use drizzle-kit push — see CONFIGURATION.md for why.

7. Build and start the API

The API dev script (node --watch dist/index.js) runs compiled output, so the project must be built before the first start and after any TypeScript changes:

# Terminal 1 — build once, then start in watch mode
set -a; source .env; set +a
pnpm --filter @familysync/api build
DEV_AUTH_BYPASS=true DB_HOST=localhost pnpm --filter @familysync/api dev

The API listens on http://localhost:3000.

8. Start the PWA dev server

# Terminal 2
pnpm --filter @familysync/pwa dev

The Vite dev server (default port 5173) proxies /health, /api, and /callback to http://localhost:3000, so you do not need CORS configuration.

Open http://localhost:5173 in your browser. With DEV_AUTH_BYPASS=true the login step is skipped and you are signed in as the dev user.

---

Common Setup Issues

pnpm: command not found after corepack enable pnpm Corepack installs pnpm into a path that may not be on your PATH in the current shell. Run hash -r or open a new terminal.

Access denied for user 'familysync'@'localhost' on migration MariaDB may still be initialising. Wait a few seconds and retry. If the error persists, verify DB_PASSWORD in .env matches MARIADB_PASSWORD in docker-compose.yml (both use ${DB_PASSWORD}).

Cannot connect to DB_HOST=mariadb The API is running on the host but .env still has DB_HOST=mariadb (the Docker network hostname). Override it inline:

DB_HOST=localhost pnpm --filter @familysync/api dev

Or set DB_HOST=localhost directly in your .env for host-side dev.

API starts but all requests return 401 / redirect to Authelia DEV_AUTH_BYPASS is not set or is not being exported to the process. Make sure you source .env with set -a; source .env; set +a or prefix the command with DEV_AUTH_BYPASS=true. The bypass only works when NODE_ENV is not production.

[FATAL] LOCAL_SESSION_SECRET is not set or is shorter than 32 characters The API refuses to start in non-bypass mode without a valid LOCAL_SESSION_SECRET. Either:

• Set DEV_AUTH_BYPASS=true in .env for local dev (bypass mode exempts the requirement), or
• Run pnpm generate-secrets and add the generated LOCAL_SESSION_SECRET value to .env.

PWA shows a blank screen after first load Run the API build step first (pnpm --filter @familysync/api build). The dev script runs dist/index.js; if dist/ is missing or stale, the API process exits immediately.

Port 3306 already in use Another local MySQL/MariaDB service is running. Stop it before starting Docker Compose, or change the host-side port in docker-compose.dev.yml.

---

Next Steps

• docs/ARCHITECTURE.md — System design, component diagram, data flow
• docs/CONFIGURATION.md — All environment variables, defaults, and per-environment guidance
• docs/DEVELOPMENT.md — Build commands, code style, and contribution workflow
• docs/deployment.md — Production deployment on Unraid via Docker Compose