# Environment Variables

<!-- AUTO-GENERATED from .env.example and deploy/compose.example.yaml -->

## Quick start

```bash
cp .env.example .env
# Fill in required values, then:
pnpm dev:local
```

## Core

| Variable              | Required | Description                                                        | Example / Default                                |
| --------------------- | -------- | ------------------------------------------------------------------ | ------------------------------------------------ |
| `NEXT_PUBLIC_APP_URL` | Yes      | Public URL of the app — used in OIDC redirect URIs and share links | `https://fam.yourdomain.com`                     |
| `DATABASE_URL`        | Yes      | Postgres connection string                                         | `postgres://famapp:famapp@localhost:5432/famapp` |
| `AUTH_SECRET`         | Yes      | Auth.js signing secret — generate with `openssl rand -base64 32`   | —                                                |

## OIDC (Authentik)

Required in production. Obtain from the Authentik admin panel after bootstrapping the provider — see `deploy/authentik/README.md`.

| Variable                  | Required   | Description                       | Example                                             |
| ------------------------- | ---------- | --------------------------------- | --------------------------------------------------- |
| `AUTH_OIDC_ISSUER`        | Yes (prod) | Authentik OIDC issuer URL         | `https://auth.yourdomain.com/application/o/famapp/` |
| `AUTH_OIDC_CLIENT_ID`     | Yes (prod) | OIDC client ID from Authentik     | —                                                   |
| `AUTH_OIDC_CLIENT_SECRET` | Yes (prod) | OIDC client secret from Authentik | —                                                   |

## Dev login

Local development only. Never set `ENABLE_DEV_LOGIN=true` in production — a startup assertion in `src/lib/dev-login-config.ts` will crash the container if you do.

| Variable             | Required | Description                                       | Default            |
| -------------------- | -------- | ------------------------------------------------- | ------------------ |
| `ENABLE_DEV_LOGIN`   | No       | Show a one-click **Dev login** button on `/login` | `false`            |
| `DEV_LOGIN_EMAIL`    | No       | Email for the auto-created dev session            | `dev@famapp.local` |
| `DEV_LOGIN_NAME`     | No       | Display name for the dev user                     | `Dev User`         |
| `DEV_HOUSEHOLD_NAME` | No       | Household created for the dev user                | `Home`             |

See `docs/dev-login.md` for the full local run procedure.

## Web Push (VAPID)

All three are required together. Generate them once with `pnpm vapid:generate` and copy all three lines into `.env`.

| Variable            | Required | Description                                   |
| ------------------- | -------- | --------------------------------------------- | ------------------------ |
| `VAPID_PUBLIC_KEY`  | Yes      | VAPID public key — also passed to the browser |
| `VAPID_PRIVATE_KEY` | Yes      | VAPID private key — server only               |
| `VAPID_SUBJECT`     | Yes      | Contact URI for push servers                  | `mailto:you@example.com` |

## ntfy (optional)

Leave both blank to disable the ntfy notification channel. Web Push is the primary channel.

| Variable     | Required | Description              | Example           |
| ------------ | -------- | ------------------------ | ----------------- |
| `NTFY_URL`   | No       | ntfy server base URL     | `https://ntfy.sh` |
| `NTFY_TOPIC` | No       | ntfy topic to publish to | `famapp-alerts`   |

## Logging

| Variable    | Required | Description        | Values                                                      |
| ----------- | -------- | ------------------ | ----------------------------------------------------------- |
| `LOG_LEVEL` | No       | Pino log verbosity | `trace`, `debug`, `info`, `warn`, `error` (default: `info`) |

## MinIO object storage

Required when the garden module is enabled. The dev compose stack starts a local MinIO instance automatically via `pnpm dev:local`.

| Variable              | Required | Description                          | Default                 |
| --------------------- | -------- | ------------------------------------ | ----------------------- |
| `MINIO_ENDPOINT`      | Yes      | MinIO server base URL                | `http://localhost:9000` |
| `MINIO_ROOT_USER`     | Yes      | MinIO root access key                | `famapp`                |
| `MINIO_ROOT_PASSWORD` | Yes      | MinIO root secret key                | `changeme`              |
| `MINIO_BUCKET`        | No       | Bucket used for garden image uploads | `garden`                |

## OpenPlantBook

Optional. Enables plant species lookup in the garden module. Free account at <https://open.plantbook.io>.

| Variable                      | Required | Description          |
| ----------------------------- | -------- | -------------------- |
| `OPENPLANTBOOK_CLIENT_ID`     | No       | OAuth2 client ID     |
| `OPENPLANTBOOK_CLIENT_SECRET` | No       | OAuth2 client secret |

## Release tooling

Only needed on the machine that cuts releases (`pnpm release`).

| Variable       | Required      | Description                                      |
| -------------- | ------------- | ------------------------------------------------ |
| `GITHUB_TOKEN` | Yes (release) | Personal access token — creates a GitHub Release |

## Production-only compose variables

Used by `deploy/compose.example.yaml`. Set in `deploy/.env` on the server — not in the local `.env`.

| Variable                                                            | Description                                                                    |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `FAMAPP_IMAGE`                                                      | Docker image tag to deploy (e.g. `registry.ginnoir.com/ginnoir/famapp:v0.4.7`) |
| `FAMAPP_PORT`                                                       | Host port to bind (default: `3000`)                                            |
| `FAMAPP_PULL_POLICY`                                                | Docker pull policy (default: `always`)                                         |
| `FAMAPP_DB_USER` / `FAMAPP_DB_PASSWORD` / `FAMAPP_DB_NAME`          | Postgres credentials for the famapp database                                   |
| `AUTHENTIK_DB_USER` / `AUTHENTIK_DB_PASSWORD` / `AUTHENTIK_DB_NAME` | Postgres credentials for the Authentik database                                |
| `AUTHENTIK_SECRET_KEY`                                              | Authentik signing key — generate with `openssl rand -base64 60`                |
| `AUTHENTIK_IMAGE_TAG`                                               | Authentik server image tag (default: `2024.12.3`)                              |
| `RUN_MIGRATIONS`                                                    | Set `false` to skip auto-migration on start (default: `true`)                  |

<!-- END AUTO-GENERATED -->