Skip to content

Configuration reference

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.