familysync/docs/GETTING-STARTED.md

<!-- generated-by: gsd-doc-writer -->

# 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 <repository-url>
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