OrbitRepos Configuration Reference¶

All configuration is managed via YAML config file and/or environment variables. Environment variables always take precedence over the config file.

Configuration Sources (priority order)¶

Environment variables (highest priority) - prefixed with ORBITREPO_
Config file - orbitrepo.yaml searched in: ., ./configs, /etc/orbitrepo
Built-in defaults (lowest priority)

Environment Variable Naming¶

Config keys map to environment variables by: - Adding the ORBITREPO_ prefix - Replacing . (dot separators) with _ (underscores) - Converting to UPPER_CASE

Example: database.ssl_mode becomes ORBITREPO_DATABASE_SSL_MODE

Server¶

HTTP server settings.

Environment Variable	YAML Key	Type	Default	Description
`ORBITREPO_SERVER_HOST`	`server.host`	string	`0.0.0.0`	Listen address
`ORBITREPO_SERVER_PORT`	`server.port`	int	`8080`	Listen port
`ORBITREPO_SERVER_READ_TIMEOUT`	`server.read_timeout`	int	`30`	HTTP read timeout (seconds)
`ORBITREPO_SERVER_WRITE_TIMEOUT`	`server.write_timeout`	int	`300`	HTTP write timeout (seconds, high for large uploads)
`ORBITREPO_SERVER_MAX_REQUEST_BODY`	`server.max_request_body`	int64	`10737418240`	Max request body size (bytes, default 10GB)
`ORBITREPO_SERVER_GRACEFUL_TIMEOUT`	`server.graceful_timeout`	int	`30`	Graceful shutdown timeout (seconds)

Database¶

PostgreSQL connection settings.

Environment Variable	YAML Key	Type	Default	Description
`ORBITREPO_DATABASE_HOST`	`database.host`	string	`localhost`	PostgreSQL host
`ORBITREPO_DATABASE_PORT`	`database.port`	int	`5432`	PostgreSQL port
`ORBITREPO_DATABASE_USER`	`database.user`	string	`orbitrepo`	Database user
`ORBITREPO_DATABASE_PASSWORD`	`database.password`	string	`orbitrepo`	Database password
`ORBITREPO_DATABASE_NAME`	`database.name`	string	`orbitrepo`	Database name
`ORBITREPO_DATABASE_SSL_MODE`	`database.ssl_mode`	string	`disable`	PostgreSQL SSL mode (`disable`, `require`, `verify-ca`, `verify-full`)
`ORBITREPO_DATABASE_MAX_OPEN_CONNS`	`database.max_open_conns`	int	`25`	Maximum open connections
`ORBITREPO_DATABASE_MAX_IDLE_CONNS`	`database.max_idle_conns`	int	`5`	Maximum idle connections
`ORBITREPO_DATABASE_MAX_CONN_LIFETIME`	`database.max_conn_lifetime`	string	`30m`	Maximum connection lifetime (Go duration)
`ORBITREPO_DATABASE_MAX_CONN_IDLE_TIME`	`database.max_conn_idle_time`	string	`5m`	Maximum connection idle time (Go duration)
`ORBITREPO_DATABASE_HEALTH_CHECK_PERIOD`	`database.health_check_period`	string	`30s`	Health check interval (Go duration)

Storage¶

Artifact storage backend. OrbitRepos supports filesystem and S3-compatible storage.

General¶

Environment Variable	YAML Key	Type	Default	Description
`ORBITREPO_STORAGE_TYPE`	`storage.type`	string	`filesystem`	Storage backend: `filesystem` or `s3`
`ORBITREPO_STORAGE_BASE_DIR`	`storage.base_dir`	string	`/var/lib/orbitrepo/data`	Base directory for filesystem storage

S3-Compatible Storage¶

Used when ORBITREPO_STORAGE_TYPE=s3. Works with AWS S3, MinIO, and other S3-compatible services. No S3 defaults are set -- all values must be provided explicitly.

Environment Variable	YAML Key	Type	Default	Description
`ORBITREPO_STORAGE_S3_ENDPOINT`	`storage.s3.endpoint`	string	(empty)	S3 endpoint URL (e.g., `http://minio:9000`). Leave empty for AWS S3.
`ORBITREPO_STORAGE_S3_REGION`	`storage.s3.region`	string	(empty)	S3 region (e.g., `us-east-1`)
`ORBITREPO_STORAGE_S3_BUCKET`	`storage.s3.bucket`	string	(empty)	S3 bucket name (required when type is `s3`)
`ORBITREPO_STORAGE_S3_ACCESS_KEY_ID`	`storage.s3.access_key_id`	string	(empty)	S3 access key ID
`ORBITREPO_STORAGE_S3_SECRET_ACCESS_KEY`	`storage.s3.secret_access_key`	string	(empty)	S3 secret access key
`ORBITREPO_STORAGE_S3_USE_PATH_STYLE`	`storage.s3.use_path_style`	bool	`false`	Use path-style addressing (set `true` for MinIO)
`ORBITREPO_STORAGE_S3_DISABLE_SSL`	`storage.s3.disable_ssl`	bool	`false`	Disable SSL for S3 connections

Authentication¶

General Auth¶

Environment Variable	YAML Key	Type	Default	Description
`ORBITREPO_AUTH_JWT_SECRET`	`auth.jwt_secret`	string	`change-me-in-production`	JWT signing secret (change in production)
`ORBITREPO_AUTH_JWT_EXPIRY`	`auth.jwt_expiry`	int	`24`	JWT token expiry (hours)
`ORBITREPO_AUTH_ADMIN_USERNAME`	`auth.admin_username`	string	`admin`	Default admin username (created on first startup)
`ORBITREPO_AUTH_ADMIN_PASSWORD`	`auth.admin_password`	string	`admin123`	Default admin password (created on first startup)
`ORBITREPO_AUTH_ALLOW_ANONYMOUS`	`auth.allow_anonymous`	bool	`false`	Allow unauthenticated read access

LDAP¶

Environment Variable	YAML Key	Type	Default	Description
`ORBITREPO_AUTH_LDAP_ENABLED`	`auth.ldap.enabled`	bool	`false`	Enable LDAP authentication
`ORBITREPO_AUTH_LDAP_HOST`	`auth.ldap.host`	string	(empty)	LDAP server hostname
`ORBITREPO_AUTH_LDAP_PORT`	`auth.ldap.port`	int	`389`	LDAP server port
`ORBITREPO_AUTH_LDAP_USE_SSL`	`auth.ldap.use_ssl`	bool	`false`	Use LDAPS (SSL/TLS)
`ORBITREPO_AUTH_LDAP_BIND_DN`	`auth.ldap.bind_dn`	string	(empty)	Bind DN for LDAP searches
`ORBITREPO_AUTH_LDAP_BIND_PASSWORD`	`auth.ldap.bind_password`	string	(empty)	Bind password for LDAP searches
`ORBITREPO_AUTH_LDAP_BASE_DN`	`auth.ldap.base_dn`	string	(empty)	Base DN for user searches
`ORBITREPO_AUTH_LDAP_USER_FILTER`	`auth.ldap.user_filter`	string	`(uid=%s)`	LDAP user search filter (`%s` = username)
`ORBITREPO_AUTH_LDAP_GROUP_FILTER`	`auth.ldap.group_filter`	string	(empty)	LDAP group search filter
`ORBITREPO_AUTH_LDAP_EMAIL_ATTR`	`auth.ldap.email_attr`	string	`mail`	LDAP attribute for email
`ORBITREPO_AUTH_LDAP_USERNAME_ATTR`	`auth.ldap.username_attr`	string	`uid`	LDAP attribute for username

OIDC (OpenID Connect)¶

Environment Variable	YAML Key	Type	Default	Description
`ORBITREPO_AUTH_OIDC_ENABLED`	`auth.oidc.enabled`	bool	`false`	Enable OIDC authentication
`ORBITREPO_AUTH_OIDC_ISSUER_URL`	`auth.oidc.issuer_url`	string	(empty)	OIDC provider issuer URL
`ORBITREPO_AUTH_OIDC_CLIENT_ID`	`auth.oidc.client_id`	string	(empty)	OIDC client ID
`ORBITREPO_AUTH_OIDC_CLIENT_SECRET`	`auth.oidc.client_secret`	string	(empty)	OIDC client secret
`ORBITREPO_AUTH_OIDC_REDIRECT_URL`	`auth.oidc.redirect_url`	string	(empty)	OIDC callback URL (e.g., `http://localhost:8080/auth/oidc/callback`)
`ORBITREPO_AUTH_OIDC_SCOPES`	`auth.oidc.scopes`	string[]	`openid,profile,email`	OIDC scopes (comma-separated in env)
`ORBITREPO_AUTH_OIDC_GROUP_SYNC_ENABLED`	`auth.oidc.group_sync_enabled`	bool	`false`	Enable OIDC group sync on login
`ORBITREPO_AUTH_OIDC_GROUPS_CLAIM`	`auth.oidc.groups_claim`	string	`groups`	JWT claim name containing group list
`ORBITREPO_AUTH_OIDC_GROUP_PREFIX`	`auth.oidc.group_prefix`	string	`oidc-`	Prefix for auto-created OIDC groups
`ORBITREPO_AUTH_OIDC_ADMIN_GROUPS`	`auth.oidc.admin_groups`	string[]	(empty)	OIDC groups that grant admin access (comma-separated in env)
`ORBITREPO_AUTH_OIDC_BROWSER_ISSUER_URL`	`auth.oidc.browser_issuer_url`	string	(empty)	Public OIDC issuer URL for browser redirects (when `issuer_url` is Docker-internal)

Logging¶

Environment Variable	YAML Key	Type	Default	Description
`ORBITREPO_LOG_LEVEL`	`log.level`	string	`info`	Log level: `debug`, `info`, `warn`, `error`
`ORBITREPO_LOG_FORMAT`	`log.format`	string	`json`	Log format: `json`, `text`

Proxy¶

Default settings for proxy (remote) repositories.

Environment Variable	YAML Key	Type	Default	Description
`ORBITREPO_PROXY_CONNECT_TIMEOUT`	`proxy.connect_timeout`	int	`10`	Connection timeout to remote (seconds)
`ORBITREPO_PROXY_READ_TIMEOUT`	`proxy.read_timeout`	int	`30`	Read timeout from remote (seconds)
`ORBITREPO_PROXY_CACHE_TTL`	`proxy.cache_ttl`	int	`1440`	Cache TTL for proxied artifacts (minutes, default 24h)

Cleanup¶

Background cleanup scheduler for artifact retention policies.

Environment Variable	YAML Key	Type	Default	Description
`ORBITREPO_CLEANUP_ENABLED`	`cleanup.enabled`	bool	`true`	Enable the background cleanup scheduler
`ORBITREPO_CLEANUP_SCHEDULE_INTERVAL`	`cleanup.schedule_interval`	int	`60`	How often the scheduler runs (minutes)

Docker Compose Variables¶

The deployments/docker-compose.yml also supports these shell/.env variables for the compose file itself:

Variable	Default	Description
`VERSION`	`dev`	Build version tag
`GIT_COMMIT`	`unknown`	Git commit hash for build
`BUILD_TIME`	`unknown`	Build timestamp
`ORBITREPO_PORT`	`8080`	Host port mapped to OrbitRepos
`DB_PASSWORD`	`orbitrepo_secret`	PostgreSQL password (used by both app and postgres containers)
`POSTGRES_PORT`	`5432`	Host port mapped to PostgreSQL
`STORAGE_TYPE`	`filesystem`	Storage backend type
`JWT_SECRET`	`change-me-in-production`	JWT signing secret
`ADMIN_PASSWORD`	`admin`	Initial admin password
`LOG_LEVEL`	`info`	Application log level
`LOG_FORMAT`	`json`	Application log format

S3 Profile Variables¶

These only apply when running with --profile s3 to start MinIO alongside OrbitRepos. You must also set the corresponding ORBITREPO_STORAGE_S3_* env vars on the orbitrepo service.

Variable	Default	Description
`S3_ACCESS_KEY`	`minioadmin`	MinIO root user / S3 access key
`S3_SECRET_KEY`	`minioadmin`	MinIO root password / S3 secret key
`S3_BUCKET`	`orbitrepo`	S3 bucket name (auto-created by minio-init)
`MINIO_API_PORT`	`9000`	Host port mapped to MinIO API
`MINIO_CONSOLE_PORT`	`9001`	Host port mapped to MinIO console

OIDC Profile Variables¶

These only apply when running with --profile oidc to start Keycloak alongside OrbitRepos.

Variable	Default	Description
`OIDC_ENABLED`	`false`	Enable OIDC authentication (set `true` with oidc profile)
`OIDC_GROUP_SYNC`	`true`	Enable OIDC group sync on login
`KEYCLOAK_PORT`	`8180`	Host port mapped to Keycloak

Quick Start Examples¶

Minimal (filesystem storage)¶

docker compose -f deployments/docker-compose.yml up -d

With S3/MinIO storage¶

STORAGE_TYPE=s3 docker compose -f deployments/docker-compose.yml --profile s3 up -d

With Keycloak OIDC¶

OIDC_ENABLED=true docker compose -f deployments/docker-compose.yml --profile oidc up -d

Test users: alice/alice123 (admin), bob/bob123 (developer), carol/carol123 (no groups).

Production overrides via `.env`¶

Create a deployments/.env file:

DB_PASSWORD=strong-db-password
JWT_SECRET=my-production-jwt-secret-at-least-32-chars
ADMIN_PASSWORD=secure-admin-pass
LOG_LEVEL=warn

Then run:

docker compose -f deployments/docker-compose.yml up -d