# 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 ```bash git clone cd familysync ``` ### 2. Enable pnpm via corepack ```bash corepack enable pnpm ``` ### 3. Install dependencies ```bash pnpm install ``` ### 4. Copy the environment file ```bash cp .env.example .env ``` Open `.env` and fill in the required values. See [docs/CONFIGURATION.md](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: ```bash pnpm generate-secrets ``` Paste the output into your `.env`. Alternatively, generate `APP_PASSWORD_ENCRYPTION_KEY` alone with: ```bash 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 ```bash 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 ```bash 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](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: ```bash # 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 ```bash # 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: ```bash 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](ARCHITECTURE.md) — System design, component diagram, data flow - [docs/CONFIGURATION.md](CONFIGURATION.md) — All environment variables, defaults, and per-environment guidance - [docs/DEVELOPMENT.md](DEVELOPMENT.md) — Build commands, code style, and contribution workflow - [docs/deployment.md](deployment.md) — Production deployment on Unraid via Docker Compose