Configuration Reference

Configuration reference

This page lists every environment variable openrunic reads, what it does, its default, and where it is read. It is for anyone configuring a workspace or a deployment.

The list is short on purpose. Configuration that has no consumer is configuration that drifts.

Database

Read by @openrunic/database. Prisma reads a package-local .env at packages/database/.env, not a root one. Copy packages/database/.env.example and fill it in.

Variable	Required	Default	What it does
DATABASE_URL	Yes, for any database work	none	The connection the application uses. May point at a connection pooler. Read by createPrismaClient in packages/database/src/client.ts, which throws a named error when it is unset.
DIRECT_URL	Recommended	falls back to DATABASE_URL	A connection straight to Postgres, bypassing any pooler. prisma.config.ts prefers this for migration commands. Locally it is usually the same value as DATABASE_URL.
SHADOW_DATABASE_URL	No	none	A throwaway database for prisma migrate diff --from-migrations, which replays the whole history. CI sets it; local development usually does not need it.

prisma.config.ts omits the datasource entirely when no URL is set, which is what keeps prisma generate and prisma validate usable with no database at all.

API

Read by apps/api, validated by a Zod schema in apps/api/src/env.ts.

Variable	Type	Default	What it does
PORT	integer, 1 to 65535	4000	The port the server binds.
NODE_ENV	development, test, production	development	Gates two behaviours: the production wiring assertion, and request logging (skipped under test).

Validation failure throws a message naming the offending variables. It never echoes their values.

Two notes. NODE_ENV is also read directly in apps/api/src/app.ts rather than through the schema, in the two places above. And there is no .env loader in apps/api; it reads the process environment as given.

NODE_ENV=production makes the built server throw at construction, because apps/api/src/index.ts builds the app with in-memory defaults and assertProductionWiring refuses them. That is deliberate: it is better to fail loudly than to serve fixtures in production.

The API does not read DATABASE_URL.

Web app

Read by apps/web. Both are NEXT_PUBLIC_, so they are inlined at build time and visible in the browser bundle. Never put a secret in either.

Variable	Default	What it does
NEXT_PUBLIC_API_MODE	mock	Only the literal string live switches to HTTP. Anything else, including unset, resolves to mock.
NEXT_PUBLIC_API_BASE_URL	http://localhost:4000	The API base URL when live.

Both are resolved once at module load in apps/web/src/lib/api/config.ts. There is no runtime toggle, so a change needs a dev-server restart or a rebuild.

There is no .env.example in apps/web, because mock mode is the default and needs no configuration.

Live mode only affects the patients, appointments, and chart clients. Admin, reports, orders, results, inbox, and billing are hardcoded to fixtures. See Web app.

Seed

Variable	Default	What it does
OPENRUNIC_SEED_FORCE	unset	The seed runner refuses to run when NODE_ENV is production unless this is set. Read by packages/database/src/seed/run.ts.

Self-host packaging

On the feat/ops-selfhost branch only, not merged.

Variable	Default	What it does
OPENRUNIC_DB_WAIT_ATTEMPTS	60	How many times the boot-time migrate container polls for the database before giving up.
NODE_IMAGE	node:22-alpine	A Docker build argument for the base image.
HUSKY	set to 0 in the image	Disables the git hook installer during an image build, where there is no git directory.

Repository variables and secrets

Not environment variables for the application, but part of how the repository is configured.

Name	Kind	What it does
DISABLE_SONAR	Repository variable	Set to true today, which skips the Sonar stage on every trigger. See Code quality bar.
SONAR_TOKEN_WEB	Secret	The scan token for the web project. Not set yet.
SONAR_TOKEN_API	Secret	The scan token for the API project. Not set yet.
SCORECARD_TOKEN	Secret, optional	A fine-grained token with read access to Administration, needed only so the OpenSSF Scorecard branch-protection check can score rather than read as inconclusive.

What does not exist yet

Naming the absences is more useful than implying completeness. There is no configuration for authentication, object storage, mail or messaging, telemetry, rate limits, CORS origins, session settings, or feature flags at the process level. Per-tenant feature flags exist as a JSON column on Organisation but are not read by anything yet.

Rules

• Only .env.example files with placeholder values belong in git.
• Validate configuration at startup and fail loudly. Report which variable is wrong, never what it contains.
• A new variable needs a default, a consumer, and a row on this page. Configuration nobody reads is configuration that drifts.

Related pages

• Getting started
• API service
• Web app
• Self-hosting
• Data model