Environment

This page documents runtime environment variables used by Kōji server code.

How Env Is Loaded

Kōji loads .env by default. You can point to a different file by setting the ENV variable before starting the server.


ENV=.env.production koji

Variable	Required	Default	Used For
`SCANNER_DB_URL`	Yes	None	Primary scanner database connection.
`CONTROLLER_DB_URL`	No	Empty (falls back to scanner DB)	Controller/instance DB connection for hybrid setups.
`KOJI_DB_URL`	Yes	None	Kōji application database connection.
`KOJI_SECRET`	No	Empty	Bearer token for `/api/v1/*` and admin login password.
`HOST`	No	`0.0.0.0`	HTTP bind host.
`PORT`	No	`8080`	HTTP bind port.
`MAX_CONNECTIONS`	No	`100`	DB pool max connections.
`LOG_LEVEL`	No	`info`	Server and SQL log level (`error\|warn\|info\|debug\|trace`).
`START_LAT`	No	`0.0`	Initial client map latitude from `/config`.
`START_LON`	No	`0.0`	Initial client map longitude from `/config`.
`NOMINATIM_URL`	No	`https://nominatim.openstreetmap.org/`	Nominatim service URL for search/import.
`TILE_SERVER`	No	Empty	Optional default tile server value exposed via `/config`.
`DANGEROUS`	No	Unset	Boolean-like flag: if set, `/config` returns `dangerous=true`.
`ENV`	No	`.env`	Selects which env file dotenv loads at startup.

Deprecated	Replacement	Notes
`DATABASE_URL`	`SCANNER_DB_URL`	Still accepted with warning log.
`UNOWN_DB_URL`	`CONTROLLER_DB_URL`	Still accepted with warning log.
`UNOWN_DB`	`CONTROLLER_DB_URL`	Still accepted with warning log.

⚠️

If KOJI_SECRET is empty, public /api/v1/* endpoints do not require Bearer auth.