Skip to content

Configuration reference

Entrepot reads a YAML file (-config flag or ENTREPOT_CONFIG) and then applies environment overrides. Every key can be overridden with ENTREPOT_ followed by its upper-cased path joined with _ — for example auth.oidc.issuerURL → ENTREPOT_AUTH_OIDC_ISSUERURL. List values take a comma-separated string; auth.gitlab and blobStores take JSON or YAML.

Validate a configuration with:

Terminal window
entrepot check-config -config config.yaml

It prints the effective configuration with secrets redacted, and fails on invalid values.

Key Env Default
server.addr ENTREPOT_SERVER_ADDR :8080
server.baseURL ENTREPOT_SERVER_BASEURL derived from each request. External URL used for OIDC redirects, the Docker token realm, rewritten metadata and as the default GitLab audience
server.trustForwardedHeaders ENTREPOT_SERVER_TRUSTFORWARDEDHEADERS false. Honour X-Forwarded-Proto/Host (and the client IP) from a reverse proxy
server.readTimeout ENTREPOT_SERVER_READTIMEOUT 0 (none)
server.shutdownTimeout ENTREPOT_SERVER_SHUTDOWNTIMEOUT 30s
database.url ENTREPOT_DATABASE_URL (_FILE supported) local dev URL
database.maxConns ENTREPOT_DATABASE_MAXCONNS 20
database.autoMigrate ENTREPOT_DATABASE_AUTOMIGRATE true
auth.sessionSecret ENTREPOT_AUTH_SESSIONSECRET (_FILE) required, ≥ 32 bytes, same on all replicas. Encrypts sessions and signs registry tokens
auth.sessionTTL ENTREPOT_AUTH_SESSIONTTL 12h
auth.bootstrapToken ENTREPOT_AUTH_BOOTSTRAPTOKEN (_FILE) disabled
auth.adminGroups / auth.adminUsers ENTREPOT_AUTH_ADMINGROUPS / ENTREPOT_AUTH_ADMINUSERS (comma-separated) none
auth.anonymousAccess ENTREPOT_AUTH_ANONYMOUSACCESS true (only affects repositories with anonymousRead)
auth.oidc.enabled ENTREPOT_AUTH_OIDC_ENABLED false
auth.oidc.issuerURL ENTREPOT_AUTH_OIDC_ISSUERURL —
auth.oidc.clientID ENTREPOT_AUTH_OIDC_CLIENTID —
auth.oidc.clientSecret ENTREPOT_AUTH_OIDC_CLIENTSECRET (_FILE) —
auth.oidc.scopes ENTREPOT_AUTH_OIDC_SCOPES openid,profile,email
auth.oidc.groupsClaim ENTREPOT_AUTH_OIDC_GROUPSCLAIM groups
auth.oidc.usernameClaim ENTREPOT_AUTH_OIDC_USERNAMECLAIM preferred_username
auth.oidc.bearerAudiences ENTREPOT_AUTH_OIDC_BEARERAUDIENCES the client ID
auth.oidc.displayName ENTREPOT_AUTH_OIDC_DISPLAYNAME Single sign-on
auth.gitlab ENTREPOT_AUTH_GITLAB (JSON/YAML list) none. Each entry: name, issuerURL, audience (default server.baseURL), api
auth.gitlab[].api — {url, token | tokenEnv | tokenFile}: a GitLab API token (scope api) for scan feedback; url defaults to issuerURL
storage.allowedRoots ENTREPOT_STORAGE_ALLOWEDROOTS /data. file blob stores must live below one of these
storage.tempDir ENTREPOT_STORAGE_TEMPDIR OS temp dir. Spool space for uploads
proxy.timeout ENTREPOT_PROXY_TIMEOUT 60s (time to response headers from an upstream)
proxy.userAgent ENTREPOT_PROXY_USERAGENT entrepot/1.0
blobStores ENTREPOT_BLOBSTORES (JSON/YAML list) none (a default file store is created when no stores exist)
log.level / log.format ENTREPOT_LOG_LEVEL / ENTREPOT_LOG_FORMAT info / json (or text)
secrets.key ENTREPOT_SECRETS_KEY (_FILE) derived from auth.sessionSecret. Encrypts secrets stored in Postgres; same on all replicas
secrets.previousKeys ENTREPOT_SECRETS_PREVIOUSKEYS (comma-separated) none. Old keys that can still decrypt during a rotation
scan.workers ENTREPOT_SCAN_WORKERS 2 in-process scan workers (0 when a separate entrepot scan-worker runs them)
scan.workDir / scan.jobTimeout / scan.pollInterval ENTREPOT_SCAN_WORKDIR / …_JOBTIMEOUT / …_POLLINTERVAL temp dir / 15m / 2s
cleanup.interval ENTREPOT_CLEANUP_INTERVAL 24h (0 disables scheduled cleanup)

_FILE variants (ENTREPOT_AUTH_SESSIONSECRET_FILE, ENTREPOT_AUTH_BOOTSTRAPTOKEN_FILE, ENTREPOT_AUTH_OIDC_CLIENTSECRET_FILE, ENTREPOT_DATABASE_URL_FILE, ENTREPOT_SECRETS_KEY_FILE) read the value from a file, which suits Kubernetes secret mounts. Durations use Go syntax (90s, 15m, 12h).

entrepot scan-worker also reads ENTREPOT_SCAN_WORKER_ADDR (or -health-addr) for its /healthz and /readyz listener.

config.yaml
server:
addr: ":8080"
baseURL: https://entrepot.example.com
trustForwardedHeaders: true
database:
url: postgres://entrepot:secret@db:5432/entrepot?sslmode=require
auth:
sessionSecret: <48 random characters>
adminGroups: [entrepot-admins]
oidc:
enabled: true
issuerURL: https://keycloak.example.com/realms/platform
clientID: entrepot
clientSecret: <secret>
groupsClaim: groups
gitlab:
- name: gitlab
issuerURL: https://gitlab.example.com
api:
tokenEnv: ENTREPOT_GITLAB_TOKEN
storage:
allowedRoots: [/data]
blobStores:
- {name: default, type: file, path: /data/default}
- name: s3
type: s3
s3: {bucket: my-artifacts, region: eu-west-2, redirectDownloads: "true"}
secrets:
key: <48 random characters>
scan:
workers: 2
cleanup:
interval: 24h

Blob stores declared in configuration are created or updated at startup. S3 settings in blobStores are strings ("true"), as above.

These are set per repository through the API, the UI or Terraform, not in the server configuration.

Field Meaning
name ^[a-z0-9][a-z0-9._-]{0,62}$ (immutable)
format raw, pypi, npm, docker, apt, yum, helm (immutable)
kind hosted, proxy, group (immutable)
blobStore store for this repository’s content (immutable)
description free text
online offline proxies serve only cached content (default true)
anonymousRead allow unauthenticated reads (default false)
hosted.allowRedeploy allow overwriting existing files/versions (default false; true for Docker, which means moving tags)
hosted.apt.distributions Apt: [{name, components, architectures, origin, label}] (default stable/main)
hosted.yum.repodataDepth Yum: directory depth for repodata, 0–5 (default 0)
proxy.remoteUrl upstream URL
proxy.username / proxy.password upstream credentials (sent only to the upstream host; the password is write-only)
proxy.metadataTtlSeconds cache time for indexes/metadata/tags (default 3600)
proxy.contentTtlSeconds cache time for artifacts (default 0 = immutable)
proxy.negativeCacheTtlSeconds cache time for upstream 404s (default 300, -1 disables)
proxy.routingRule routing rule restricting what is fetched upstream
group.members ordered member repositories of the same format
group.preferHosted npm/PyPI/Helm: never take a name from proxies if a hosted member has it (default true)
scan {scanners, mode: off|warn|quarantine, severityThreshold, onUpload, onProxyFetch, blockUntilScanned, distro}. See scanning
cleanup.policies cleanup policies to apply. See cleanup

PUT /api/v1/repositories/{name} replaces all mutable fields, so send the complete definition.