Getting Started

This guide walks you through setting up a local Patrimoine development environment. You can run the full stack in containers (recommended) or develop the backend and frontend separately without containers.

Prerequisites

Podman 6+ (or Docker) — includes podman compose.
(Optional) An OIDC provider such as Authentik. If you don’t have one, the app falls back to local email/password auth.

Quick Start with Containers

1. Clone the repository

git clone <url> patrimoine
cd patrimoine

2. Create the data directory

mkdir -p ./data

This directory is bind-mounted into the backend container and holds the SQLite database file (patrimoine.db).

3. Copy the environment file

cp backend/container/env.example backend/container/.env

The frontend, web and PostgreSQL containers have their own optional templates (frontend/container/env.example, web/container/env.example, data/container/env.example); the defaults work without them. See Environment Variables.

4. Configure `backend/container/.env`

Open backend/container/.env and set the following:

Variable	Value
`JWT_SECRET`	A long random string. Generate one with: `python -c "import secrets; print(secrets.token_urlsafe(48))"`
`OIDC_ENABLED`	`true` to use OIDC (also needs `OIDC_CLIENT_ID`); leave unset for local auth only
`OIDC_CLIENT_ID`	Your OIDC client ID (only used when `OIDC_ENABLED=true`)
`OIDC_CLIENT_SECRET`	Your OIDC client secret (if using OIDC)
`OIDC_ISSUER`	OIDC discovery URL (e.g. `http://localhost:9000/application/o/patrimoine/`)
`OIDC_REDIRECT_URI`	Optional. Defaults to `FRONTEND_URL` + `/auth/callback`; set it only if the registered redirect differs
`FRONTEND_URL`	`http://localhost:8080` (or your production URL)
`REGISTRATION_ENABLED`	`true` — needed to create the first account, then set to `false`
`ADMIN_EMAILS`	Your account’s email — promotes an OIDC account to admin (optional, OIDC only, see step 7)

5. Start the application

podman compose --env-file backend/container/.env up --build

(Or ./podman.sh build && ./podman.sh up, which reads the per-container env files itself.) The first build takes 2–5 minutes (backend, frontend and docs images). Subsequent starts are instant thanks to layer caching.

6. Access the app

Open http://localhost:8080 in your browser. The documentation site is served at http://localhost:8082 (SITE_PORT in web/container/.env).

OIDC configured: you will be redirected to Authentik to authenticate.
OIDC off (the default): the local login page appears. Click “Créer un compte” to register if REGISTRATION_ENABLED=true.

7. First-run setup

Create your account via “Créer un compte”.

Set REGISTRATION_ENABLED=false in backend/container/.env and restart:

podman compose down && podman compose --env-file backend/container/.env up -d

Admin access: with local auth, the first account registered on an empty instance is made admin automatically — ADMIN_EMAILS never applies to local accounts. With OIDC, if you set ADMIN_EMAILS to your account’s email in step 4, log back in (or refresh) to complete the promotion. Either way your account gains an admin-only “Users” page for managing other accounts, from which you can invite additional users by email without ever re-enabling public registration. See Environment Variables and Troubleshooting for details.

Local Development Without Containers

For faster iteration, run the backend and frontend directly on your host.

Backend

cd backend
uv sync
uv run uvicorn app.main:app --reload --port 8000

Frontend

cd frontend
npm ci
npm run dev

The Vite dev server runs on port 5173 and proxies /api and /auth requests to the backend on port 8000.

`.env` overrides for local dev

The backend reads a .env file from its working directory, so for local runs copy the backend template there (cp backend/container/env.example backend/.env) and uncomment (or add) these lines in backend/.env:

DEBUG=true
FRONTEND_URL=http://localhost:5173
OIDC_REDIRECT_URI=http://localhost:8000/auth/callback
DATABASE_URL=sqlite+aiosqlite:///data/patrimoine.db

Running CI Checks Locally

The ci-local.sh script replicates the Forgejo CI pipeline locally:

./ci-local.sh              # all checks (backend + frontend + security)
./ci-local.sh backend      # lint, test, OpenAPI schema, migration round-trip
./ci-local.sh backend-cov  # backend whole suite with coverage (slower; not part of 'all')
./ci-local.sh frontend     # lint, type check, test, build, size limit, bundle checks
./ci-local.sh security     # pip-audit, npm audit, gitleaks secret scan

See Testing for details on each test layer.