All configuration is by environment variable. A variable that is set but cannot be read (LFSX_BIND, LFSX_AUTH, or a size or duration below) stops the server at boot with an error naming the variable and the value. An unset or empty variable keeps its default.
| Variable | Default | Purpose |
|---|---|---|
LFSX_BIND |
0.0.0.0:8080 |
listen address |
LFSX_METRICS_BIND |
unset | listen address for /metrics alone, such as 0.0.0.0:9090; when set, the main listener no longer serves /metrics at all, so an ingress or proxy in front of it cannot expose it; unset keeps /metrics on LFSX_BIND |
LFSX_STORAGE_ROOT |
/var/lib/lfsx |
root of the object store |
LFSX_PUBLIC_URL |
the requested host | public URL used to build transfer links; set it behind a proxy, because the fallback trusts the caller's headers |
LFSX_AUTH |
github |
permission source: github, gitlab, gitea (or forgejo, the same provider), or disabled to accept every request |
LFSX_GITHUB_API_URL |
https://api.github.com |
API root, point it at your GitHub Enterprise host |
LFSX_GITLAB_API_URL |
https://gitlab.com/api/v4 |
API root, point it at your self-managed GitLab |
LFSX_GITEA_API_URL |
none, required | API root of your Gitea or Forgejo instance, https://git.example.com/api/v1 |
LFSX_ANONYMOUS_READ |
false |
true to let a request with no credentials read a repository the forge serves publicly |
LFSX_ALLOWED |
none | repositories this server serves, same syntax as LFSX_RESTRICTED; anything else is 404 without asking the forge. Unset serves every repository on the forge, see Allowed namespaces |
LFSX_FORGES |
none | more forges served beside the one LFSX_AUTH names, each under /-/{name}/ and configured by LFSX_FORGE_<NAME>_*, see Several forges |
LFSX_RESTRICTED |
none | repositories whose objects take write access to read, comma-separated, org/repo or org/prefix-* or org/* |
LFSX_AUTH_CACHE_TTL |
60 |
seconds a granted permission is reused before being checked again |
LFSX_AUTH_REJECTION_TTL |
10 |
seconds a refusal is remembered, so a bad token cannot hammer the forge |
LFSX_AUTH_LOOKUP_BUDGET |
600 |
forge lookups a minute this server will spend, counting only what the caches could not answer; 0 removes the ceiling |
LFSX_DASHBOARD |
false |
true to serve the web dashboard at /-/dashboard/, see Dashboard |
LFSX_DASHBOARD_REPO |
none | org/repo whose admins may sign in to the dashboard with their forge token; required with it unless LFSX_AUTH=disabled |
LFSX_DASHBOARD_FORGE |
the main forge | the named forge LFSX_DASHBOARD_REPO lives on, one of LFSX_FORGES |
LFSX_DASHBOARD_DIR |
/usr/share/lfsx/dashboard |
where the dashboard's built pages are |
LFSX_GITHUB_APP_ID |
unset | a GitHub App id, giving the server its own identity (and quota) for the anonymous public-repository lookup |
LFSX_GITHUB_APP_KEY_FILE |
unset | path to the App's RSA private key in PEM form; comes together with the id, one without the other refuses to start |
LFSX_GC_GRACE |
1209600 |
seconds an object must have been untouched before collection can take it |
LFSX_STAGING_MAX_AGE |
86400 |
seconds before an interrupted upload's leftovers are reclaimed, on the volume and in the bucket |
LFSX_LOCK_MAX_AGE |
never | whole seconds a lock may go untouched before anyone can take it |
LFSX_MAX_OBJECT_SIZE |
unlimited | whole bytes, digits only (5Gi is refused), an object may reach this before the server refuses it |
LFSX_REPO_QUOTA |
unlimited | whole bytes, digits only, a single repository may hold this |
LFSX_MAX_CONCURRENT_TRANSFERS |
128 |
uploads and downloads served at once; the transfer past the cap is answered 503 with Retry-After rather than queued; 0 removes the cap |
LFSX_TRANSFER_IDLE_TIMEOUT |
60 |
whole seconds an upload or download may go without moving a chunk before its body is cut and its transfer slot freed; 0 is ignored |
LFSX_STORAGE |
local |
s3 to keep objects in a bucket instead of on the volume, azure for a Blob Storage container, gcs for Cloud Storage |
LFSX_S3_ENDPOINT / LFSX_S3_BUCKET / LFSX_S3_REGION |
unset | where the bucket is; endpoint and bucket are required with LFSX_STORAGE=s3 |
LFSX_S3_ACCESS_KEY / LFSX_S3_SECRET_KEY |
unset | credentials for it, required with LFSX_STORAGE=s3 |
LFSX_S3_PATH_STYLE |
true |
false for virtual-host addressing; MinIO and Garage want path style |
LFSX_S3_PRESIGN |
false |
true to hand transfers to the bucket instead of streaming them through the server, ignored for downloads when compression or encryption is configured, and ignored entirely if the bucket does not prove it verifies upload checksums |
LFSX_S3_CACHE_DIR |
unset | directory holding a local copy of what the bucket serves, so a second reader does not pay the round trip again |
LFSX_AZURE_ACCOUNT / LFSX_AZURE_CONTAINER |
unset | the storage account and container, required with LFSX_STORAGE=azure |
LFSX_AZURE_ENDPOINT |
https://<account>.blob.core.windows.net |
blob endpoint, for Azurite, a private endpoint or a sovereign cloud |
LFSX_AZURE_ACCOUNT_KEY / LFSX_AZURE_SAS_TOKEN |
unset | at most one; neither authenticates with the managed or workload identity, see Azure |
LFSX_GCS_BUCKET |
unset | the bucket, required with LFSX_STORAGE=gcs |
LFSX_GCS_CREDENTIALS |
unset | a service account key file, none for an emulator, or unset for the metadata server and workload identity, see Cloud Storage |
LFSX_GCS_ENDPOINT |
https://storage.googleapis.com |
API endpoint, for an emulator or a private endpoint |
LFSX_S3_CACHE_MAX_BYTES |
unset | bytes the cache may hold before the least recently used entries are dropped; required with the directory, which does nothing without it |
LFSX_COMPRESSION |
none |
zstd, or zstd:1…zstd:19 to pick the level, to compress objects at rest |
LFSX_SESSION_KEY_FILE |
unset | path to a file holding a 32-byte key as 64 hex characters. Signs dashboard sessions, access*.json and dashboard-tokens.json; without it the key is kept in the store and anyone who can write there can forge all three. See Dashboard |
LFSX_ENCRYPTION_KEY_FILE |
unset | path to a file holding one or more 32-byte keys as hex, to encrypt objects at rest |
LFSX_ENCRYPTION_KEY_COMMAND |
unset | command whose stdout is read exactly like the key file, for keys that must never rest on disk; mutually exclusive with the file, setting both refuses to start |
RUST_LOG |
info |
log filter (tracing_subscriber syntax) |
LFSX_OTLP_ENDPOINT |
unset | HTTP traces URL of an OTLP collector (http://collector:4318/v1/traces); unset means the tracing layer is not even installed |
Set LFSX_PUBLIC_URL behind a proxy. Unset, the origin is built from the Host and
X-Forwarded-Proto the caller sent, and those are a fact about the deployment only for as long as
something in front is rewriting both. The URLs in a batch answer are where the client sends the
object, with its credential attached, so a caller who chooses the header chooses where its own token
goes, and anything caching that answer serves the choice to whoever asks next. The server says so at
startup when it is unset and authentication is on.
The fallback is not left wide open in the meantime. The scheme has to be http or https, and the
host has to be a host: a Host carrying a / or an @ is refused and the origin falls back to
localhost, which is useless to everybody and dangerous to nobody. real.example@evil.example is
the one that matters, because it resolves to the second name with the first read as a username.
LFSX_PUBLIC_URL is echoed in the batch response, and the client reconnects to it for every
object: if it is wrong, negotiation succeeds and every transfer then fails.
Left unset, the server answers on whatever host the request arrived at, honouring
X-Forwarded-Proto from the proxy in front. That is what you want when the same server is reached
under more than one name (a public host and an internal one, say) since a single fixed value
would be wrong for half the clients. Set it when you want to pin one name regardless of how the
request arrived; an explicit value always wins over the request.