Lucas Berger
0b4266628b
- CLAUDE.md: remove Redis constraint, ioredis library row, Redis architecture sentence, update compose comment - README.md: remove Redis from prereqs, quick-start command, compose description, tech-stack live-sync row - docs/ARCHITECTURE.md: delete Redis infrastructure table row - docs/CONFIGURATION.md: remove Redis localhost:6379 mention from dev section - docs/deployment.md: delete redis services table row - docs/DEVELOPMENT.md: remove prereq mention, heading, two up commands, expose bullet, stack comment - docs/GETTING-STARTED.md: prereq row, up command, prose mention - docs/TESTING.md: 'API and MariaDB' (was API, MariaDB, and Redis) - apps/pwa/e2e/README.md: delete Redis on :6379 bullet - apps/pwa/playwright.config.ts: two comments updated (API+MariaDB, not API+MariaDB+Redis)
155 lines
6.0 KiB
Markdown
155 lines
6.0 KiB
Markdown
<!-- 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 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
|
|
```
|
|
|
|
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
|
|
|
|
```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
|