Environment Variables

All Drevnix configuration is done through environment variables. There are no configuration files.

Required

Variable	Description
ENCRYPTION_KEY	Secret key used to encrypt upstream registry credentials at rest (AES256-GCM). Generate with openssl rand -hex 32. Must be set before the first start and must not change after credentials have been stored.

Initial Bootstrap

These are optional and only used on first startup. Once an admin account exists they are ignored.

Variable	Default	Description
DREVNIX_INITIAL_ADMIN_USERNAME	(unset)	If set, Drevnix creates an admin account with this username on first startup if no accounts exist yet. Equivalent to running drevnix init-admin interactively.
DREVNIX_INITIAL_ADMIN_PASSWORD	(unset)	Password for the account created by DREVNIX_INITIAL_ADMIN_USERNAME. Required when DREVNIX_INITIAL_ADMIN_USERNAME is set.

Database

Variable	Default	Description
JDBC_URL	jdbc:sqlite:/data/drevnix.db?journal_mode=WAL&synchronous=NORMAL&busy_timeout=30000&foreign_keys=on	JDBC connection URL. Credentials are embedded in the URL, e.g. jdbc:postgresql://user:password@host:5432/drevnix.

Database Connection Pool

Variable	Default	Description
DB_POOL_SIZE	25	Maximum number of connections in the HikariCP pool.
DB_CONNECTION_TIMEOUT_MS	30000	How long (ms) to wait for a connection from the pool before throwing an error.
DB_IDLE_TIMEOUT_MS	600000	Remove idle connections after this many ms (10 minutes).
DB_MAX_LIFETIME_MS	1800000	Retire connections after this many ms to prevent stale handles (30 minutes).

Networking

Variable	Default	Description
PROXY_HTTP_PORT	8000	Port for the Docker Registry V2 proxy endpoint.
PROXY_HTTP_HOST	0.0.0.0	Address to bind the proxy port to.
PORTAL_HTTP_PORT	8001	Port for the web portal.
PORTAL_HTTP_HOST	127.0.0.1	Address to bind the portal to. Defaults to loopback — change to 0.0.0.0 only if you need direct external access (prefer a reverse proxy instead).
API_HTTP_PORT	8002	Port for the REST API.
API_HTTP_HOST	127.0.0.1	Address to bind the API to. Defaults to loopback — change to 0.0.0.0 only if you need direct external access (prefer a reverse proxy instead).
TRUSTED_PROXIES	(unset)	Controls client IP resolution for audit logs and rate limiting. unset: X-Forwarded-For is ignored, remote-addr always used — for direct internet-facing deployments. *: X-Forwarded-For always trusted, leftmost token used as client IP — use when behind any proxy/load balancer and the app is not directly reachable from the internet. CIDR list (e.g. 10.0.0.0/8,172.16.0.0/12): X-Forwarded-For trusted only when remote-addr falls within the listed ranges — for precise proxy trust control.

Pull-Through Cache

Variable	Default	Description
CACHE_ENABLED	false	Enable blob caching. Requires a license with cache feature.
CACHE_DIR	/data/cache	Directory on disk for cached blobs. Safe to lose — it is purely a cache and will be repopulated on next pull.
CACHE_MAX_SIZE_BYTES	10737418240	Maximum disk usage in bytes (default: 10 GB). LRU eviction applies when reached. Example: 53687091200 for 50 GB.
CACHE_ENTRY_TTL_SECONDS	86400	How long a cached blob is considered fresh in seconds (default: 24 hours).
CACHE_MIN_HITS_SHORT	3	Hits required in the short admission window.
CACHE_WINDOW_SHORT_SECONDS	600	Duration of the short admission window (10 minutes).
CACHE_MIN_HITS_LONG	10	Hits required in the long admission window.
CACHE_WINDOW_LONG_SECONDS	3600	Duration of the long admission window (1 hour).

Audit Log

Variable	Default	Description
AUDIT_ENABLED	false	Enable audit logging. Must be set to true to record pull events.
AUDIT_RETENTION_DAYS	90	Days of audit log entries to retain. Older entries are pruned automatically. Controlled by license.

Upstream HTTP Client

Variable	Default	Description
UPSTREAM_TIMEOUT_MS	30000	Request timeout (ms) for metadata calls to upstream registries — token fetch, manifest lookup, version check.
UPSTREAM_BLOB_TIMEOUT_MS	300000	Request timeout (ms) for blob/layer pulls. Covers establishing the stream; body transfer continues until EOF once headers are received.

Portal

Variable	Default	Description
PORTAL_COOKIE_SECURE	true	Sets the Secure flag on session cookies. Set to false only when running without TLS on a local or internal network.

Server

Variable	Default	Description
JETTY_STOP_TIMEOUT_MS	5000	Graceful shutdown timeout (ms). Drevnix waits this long for in-flight requests to finish before forcing a shutdown.

---

Generating a secure ENCRYPTION_KEY

openssl rand -hex 32

Once upstream credentials are stored, the ENCRYPTION_KEY must not change. If you need to rotate it, use the change-encryption-key CLI command. This re-encrypts all stored credentials under the new key without downtime.