Backend is split between:
apps/api- Fastify HTTP API- PostgreSQL - primary application database
In production monolith deployments, the Fastify process also serves apps/web/dist when STATIC_ASSETS_DIR points at the built frontend. API routes remain under /api/*; client-side web routes fall back to index.html.
Design docs:
docs/practice-queue-design.md- queue-backed practice selection architecture, migration, and observability
Common commands:
docker compose up -d garagevp run --filter @inko/api devvp run db:migratevp run --filter @inko/api testvp run --filter @inko/api lintvp run --filter @inko/api build
Mail provider envs (apps/api):
MAIL_PROVIDER=log|resendMAIL_FROM=<from address>RESEND_API_KEY=<required when MAIL_PROVIDER=resend>MAGIC_LINK_LOGIN_URL=<optional override, defaults to ${FRONTEND_URL}/login>
Database envs:
apps/api/.env:DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/inko- optional:
DATABASE_POOL_MAX=10 API_PUBLIC_URL=http://localhost:5173when using the Vite/apiproxy- optional:
STATIC_ASSETS_DIR=apps/web/dist
Object storage envs:
OBJECT_STORAGE_ENDPOINT=http://127.0.0.1:3900OBJECT_STORAGE_REGION=garageOBJECT_STORAGE_BUCKET=inko-mediaOBJECT_STORAGE_ACCESS_KEY_ID=<garage key id>OBJECT_STORAGE_SECRET_ACCESS_KEY=<garage secret>OBJECT_STORAGE_FORCE_PATH_STYLE=true
Production R2 env formats:
OBJECT_STORAGE_ENDPOINT:https://<accountid>.r2.cloudflarestorage.comOBJECT_STORAGE_REGION:autoOBJECT_STORAGE_ACCESS_KEY_ID: R2 API token access key IDOBJECT_STORAGE_SECRET_ACCESS_KEY: R2 API token secret access keyOBJECT_STORAGE_BUCKET: existing R2 bucket name
Local bootstrap:
- Use your existing local PostgreSQL instance
- Optional: start Garage with
docker compose up -d garagefor local S3-compatible testing - Garage bootstraps the single local node,
inko-mediabucket, andinko-appkey automatically - Use these local compose credentials in
apps/api/.env:OBJECT_STORAGE_ACCESS_KEY_ID=GKb599967dd3416890fee1b9bfOBJECT_STORAGE_SECRET_ACCESS_KEY=68af3881281301775c8a62b05c2cd30e40d7572bb8fa33b0c8945538a60c658d
- Run
vp run db:migrate - Then start the API or run tests
Auth notes:
- The app now uses API-issued JWTs and email magic links only.
- Magic-link tokens are stored in PostgreSQL.
- Legacy OIDC verification and older frontend auth providers have been removed.
- Optional OAuth providers are now first-party API flows:
AUTH_GITHUB_ID,AUTH_GITHUB_SECRETAUTH_GOOGLE_ID,AUTH_GOOGLE_SECRET- frontend button gates remain
VITE_AUTH_GITHUB_ENABLED=trueandVITE_AUTH_GOOGLE_ENABLED=true
- OAuth completion now uses a short-lived HTTP-only cookie handoff instead of putting the JWT in the redirect URL.