Files

T

Lucas Berger 982438dc10 style(13-03): apply Prettier formatting across repo

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.

2026-06-11 20:35:18 -04:00

5.0 KiB

Raw Blame History

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 and Redis 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 — 64 hex characters; generate with:

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

DEV_AUTH_BYPASS=true — bypasses the live Authelia OIDC flow for local dev
DB_HOST=localhost — the dev Docker Compose exposes MariaDB on the host at localhost:3306

First Run

5. Start the database services

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

This starts MariaDB (bound to localhost:3306) and Redis (localhost:6379) 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.

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/deployment.md — Production deployment on Unraid via Docker Compose

5.0 KiB Raw Blame History