| Variable |
Default |
Description |
BIND_ADDRESS |
— |
Address and port the server binds to, e.g. 0.0.0.0:3000. |
FERROBOX_PORT |
3000 |
Host-side port published by the bundled Compose file. Only relevant to that Compose setup, not to the binary itself. |
PUBLIC_BASE_URL |
http://127.0.0.1:3000 |
The externally reachable base URL for this instance. Used to build redirect URLs, including the OIDC callback. |
DATABASE_URL |
— |
Postgres connection string, e.g. postgres://user:pass@host:5432/db. |
FRONTEND_DIR |
— |
Path to the built frontend assets. Set automatically in the published Docker image — only relevant if you’re running the backend binary directly against a separately-built frontend. |
| Variable |
Default |
Description |
ADMIN_USERNAME |
admin |
Username for the built-in admin account. |
ADMIN_PASSWORD |
admin |
Password for the built-in admin account. Change this before exposing the instance to anyone else. |
SESSION_TTL_HOURS |
12 |
How long a login session (password or SSO) stays valid. |
| Variable |
Default |
Description |
POSTGRES_USER |
— |
Postgres username. |
POSTGRES_PASSWORD |
— |
Postgres password. |
POSTGRES_DB |
— |
Postgres database name. |
POSTGRES_PORT |
5432 |
Host-side port Postgres is published on (Compose only). |
Metadata is in PostgreSQL. Bytes go to an S3-compatible bucket or to a
directory, one place for the whole instance. With S3, the FerroBox process
does not keep the bytes. With the directory, the bytes are on a volume
mounted into that same process. Switching storage backends does not copy
objects. Settings shows Directory /var/lib/ferrobox/blobs or
S3 bucket ferrobox.
| Variable |
Default |
Description |
STORAGE_BACKEND |
s3 |
s3 uses the S3_* variables. filesystem uses STORAGE_PATH and does not need S3. |
STORAGE_PATH |
— |
Directory for artifact bytes when STORAGE_BACKEND=filesystem. The directory install uses /var/lib/ferrobox/blobs. |
These apply when STORAGE_BACKEND is unset or s3.
| Variable |
Default |
Description |
S3_ENDPOINT_URL |
— |
Endpoint FerroBox talks to — your own S3-compatible endpoint, or the bundled Garage service (http://garage:3900 inside Compose). |
S3_REGION |
— |
Region name your S3-compatible provider expects. |
S3_ACCESS_KEY_ID |
— |
Access key for the bucket. |
S3_SECRET_ACCESS_KEY |
— |
Secret key for the bucket. |
S3_BUCKET |
— |
Bucket name FerroBox stores artifacts in. The default Garage install uses ferrobox. |
S3_FORCE_PATH_STYLE |
true |
Path-style addressing for the S3 endpoint. The bundled Garage setup needs it. |
These only matter if you’re using the Garage
service from the bundled Compose file. If you point FerroBox at your own
S3-compatible bucket, or use the directory, you don’t need any of them.
| Variable |
Default |
Description |
GARAGE_RPC_SECRET |
— |
Shared secret between Garage nodes. Generate with openssl rand -hex 32. |
GARAGE_ADMIN_TOKEN |
— |
Token for Garage’s admin API, used by the init/bootstrap step. |
GARAGE_METRICS_TOKEN |
— |
Token for Garage’s metrics endpoint. |
GARAGE_RPC_PUBLIC_ADDR |
garage:3901 |
Address other Garage nodes use to reach this one. 127.0.0.1:3901 from the host. |
These seed the feed on first boot, when the table is empty. After you
save the Vulnerability feed page, that saved reference and public key
win. The
public key file in the product repository is
osv-sync.pub.pem.
See Vulnerability feed.
| Variable |
Default |
Description |
OSV_FEED_PATH |
— |
Optional local ferrobox-osv-index v1 file, JSON or gzip. When set, assays use this file instead of api.osv.dev. An index imported with POST /api/security/osv-feed replaces it. |
OSV_SYNC_REF |
— |
OCI reference of the signed index, for example ghcr.io/ferrobox/osv-db:2026-10-03. The reference includes the date. |
OSV_SYNC_KEY |
— |
PEM public key for that artifact. |
OSV_SYNC_PUBKEY_B64 |
— |
The same public key, base64-encoded. |
OSV_SYNC_TOKEN |
— |
Optional bearer token for a private registry. |
OSV_SYNC_INTERVAL_HOURS |
24 |
Hours between pulls. The first pull runs at startup. |
A missing or invalid signature does not replace the active index. An
air-gapped install uses oras pull and imports the file. It does not use
docker save, and the index is not a GitHub Release.
There’s a single switch here: if OIDC_ISSUER or OIDC_CLIENT_ID is
empty, FerroBox doesn’t talk to any identity provider, doesn’t mount the
SSO route, and the UI hides the SSO login button. Everything below is
optional and only takes effect once both are set.
| Variable |
Default |
Description |
OIDC_ISSUER |
— |
Issuer URL of your identity provider. |
OIDC_CLIENT_ID |
— |
OAuth client ID registered with that provider. |
OIDC_CLIENT_SECRET |
— |
OAuth client secret for that client. |
OIDC_REDIRECT_URI |
— |
Callback URL FerroBox registers with the provider. |
OIDC_SUCCESS_REDIRECT |
— |
Where the browser is sent after a successful login (and federated logout), if you’re not using the default {PUBLIC_BASE_URL} target — e.g. a separate frontend dev server. |
OIDC_SCOPES |
— |
OAuth scopes requested during login. |
OIDC_ADMIN_ROLES |
— |
Role/claim values that map to the admin role. |
OIDC_DEVELOPER_ROLES |
— |
Role/claim values that map to the developer role. |
OIDC_READER_ROLES |
— |
Role/claim values that map to the read-only role. |
OIDC_ROLE_CLAIM |
— |
Name of the token claim that carries the role/group values above. |
OIDC_GROUP_CLAIM |
— |
Name of the token claim that carries group membership, if different from the role claim. |
OIDC_AUTO_CREATE_GROUPS |
true |
Whether groups referenced by an SSO login are created automatically if they don’t exist yet. |
For a worked example, the product repo’s bundled Compose file can start a
throwaway Keycloak instance to test against (docker compose --profile sso up -d keycloak) — see the Quickstart.