Environment Variables¶
All runtime configuration is injected via environment variables. The backend reads
them at startup from the backend.env file (loaded by Docker Compose via env_file).
The frontend reads a small subset baked in at build time.
Docker Compose variable escaping
In any file loaded with env_file:, literal $ characters must be escaped as $$.
This affects bcrypt hashes ($$2b$$12$$...) and any value containing a dollar sign.
Backend variables¶
Authentication & security¶
| Variable | Type | Default | Required | Description |
|---|---|---|---|---|
JWT_SECRET_KEY |
string |
— | Yes | HMAC-SHA256 signing key for JWT tokens. Generate with openssl rand -hex 32. Minimum 32 characters. The application refuses to start in production if this is empty or set to a known-weak default. |
JWT_EXPIRE_MINUTES |
integer |
60 |
No | Token lifetime in minutes. Tokens expire and must be re-issued after this period. API tokens have their own expiry set at creation time. |
ADMIN_USERNAME |
string |
admin |
No | Username of the bootstrap admin account, created automatically on first startup when users.db does not exist. |
ADMIN_PASSWORD_HASH |
string |
— | Yes | bcrypt hash of the admin password. Generate with python -c "from passlib.hash import bcrypt; print(bcrypt.hash('password'))". Escape every $ as $$ in the env file. |
TRUSTED_PROXIES |
string |
127.0.0.1,172.16.0.0/12,192.168.0.0/16 |
No | Comma-separated list of IP addresses or CIDR ranges trusted to set X-Forwarded-For. Used by the rate limiter (slowapi) to extract the real client IP when behind a reverse proxy. |
CORS_ORIGINS |
string |
http://localhost:3003 |
No | Comma-separated list of allowed CORS origins. Include your frontend URL in production (e.g. https://repod.example.com). |
Storage paths¶
These variables control where Repod stores its data. The defaults match the Docker Compose volume mounts and should not be changed unless you know what you are doing.
| Variable | Type | Default | Description |
|---|---|---|---|
POOL_DIR |
path |
/repos/pool |
Directory where validated package binaries are stored. Served read-only by the APT/RPM Nginx container. |
MANIFEST_DIR |
path |
/repos/manifests |
Directory for per-package JSON manifests and the central index.json catalog. |
STAGING_INCOMING |
path |
/repos/staging/incoming |
Temporary landing zone for uploaded files before validation. Never served over HTTP. |
STAGING_QUARANTINE |
path |
/repos/staging/quarantine |
Destination for files that failed validation or were blocked by CVE policy. |
AUDIT_DIR |
path |
/repos/audit |
Append-only JSONL audit log files, one per day (YYYY-MM-DD.jsonl). |
INDEX_PATH |
path |
/repos/manifests/index.json |
Path to the central package index JSON file. |
INDEX_DIR |
path |
/repos/package-index |
Directory for the SQLite package index database (packages.db) used by the import and sync features. |
IMPORTS_DIR |
path |
/repos/imports |
Working directory for packages imported from external sources. |
AUTH_DB_PATH |
path |
/repos/auth/users.db |
SQLite database for user accounts. Created automatically on first startup. |
SETTINGS_PATH |
path |
/repos/settings.json |
Persistent settings file (LDAP config, webhook, CVE policy, retention, etc.). |
SECURITY_DIR |
path |
/repos/security |
Directory for CVE decisions, CISA KEV cache, and EPSS cache. |
GNUPG_HOME |
path |
/repos/gnupg |
GPG keyring directory shared between the backend and the repository container. |
NGINX_LOGS_DIR |
path |
/repos/logs |
Directory where the repository Nginx container writes access.log. Parsed by the download statistics endpoint. |
CLAMAV_DB_DIR |
path |
/var/lib/clamav |
ClamAV signature database directory. Populated by freshclam at startup and updated daily. |
GRYPE_DB_CACHE_DIR |
path |
/repos/grype-db |
Grype vulnerability database cache. Updated automatically when stale (> 24 h). |
APT-specific paths¶
| Variable | Type | Default | Description |
|---|---|---|---|
ADD_DEB_SCRIPT |
path |
/scripts/add-deb.sh |
Path to the shell script that invokes reprepro includedeb. This script runs inside the backend container and writes to the shared /repos/ volume. |
REPREPRO_BASE |
path |
/repos |
Base directory passed to reprepro -b. Reprepro expects conf/, db/, dists/, and pool/ under this path. |
DISTS_DIR |
path |
/repos/dists |
APT distribution tree managed by reprepro. Served by the depot-apt Nginx container. |
CONF_DIR |
path |
/repos/conf |
Reprepro configuration directory. Contains distributions file generated at initialization. |
RPM-specific paths¶
| Variable | Type | Default | Description |
|---|---|---|---|
ADD_RPM_SCRIPT |
path |
/scripts/add-rpm.sh |
Path to the shell script that copies the .rpm to the distribution directory and invokes createrepo_c --update. |
RPM_REPO_BASE |
path |
/repos |
Base directory for RPM distribution trees. Each distribution creates a subdirectory under this path. |
External integrations¶
| Variable | Type | Default | Description |
|---|---|---|---|
LDAP_URL |
string |
— | LDAP server URL (e.g. ldap://dc.example.com:389 or ldaps://dc.example.com:636). Leave empty to disable LDAP authentication. |
LDAP_BIND_DN |
string |
— | Distinguished name of the service account used to bind to the LDAP directory. |
LDAP_BIND_PASSWORD |
string |
— | Password for the LDAP bind account. |
LDAP_BASE_DN |
string |
— | Base DN for user search (e.g. ou=users,dc=example,dc=com). |
LDAP_USER_ATTR |
string |
sAMAccountName |
LDAP attribute used as the username (Active Directory: sAMAccountName; OpenLDAP: uid). |
SMTP_HOST |
string |
— | SMTP server hostname for email notifications (SLA alerts, webhook fallback). |
SMTP_PORT |
integer |
587 |
SMTP port. Use 465 for implicit TLS, 587 for STARTTLS. |
SMTP_USER |
string |
— | SMTP authentication username. |
SMTP_PASSWORD |
string |
— | SMTP authentication password. |
SMTP_FROM |
string |
— | Sender address for outgoing emails. |
WEBHOOK_URL |
string |
— | URL to POST JSON event payloads on security events (CVE blocks, SLA breaches). |
Runtime behavior¶
| Variable | Type | Default | Description |
|---|---|---|---|
ENV |
string |
development |
Set to production to enable strict mode (rejects weak JWT_SECRET_KEY, enforces HTTPS headers). |
APP_VERSION |
string |
dev |
Version string returned by the /health endpoint. Set to a semver tag in production images. |
Frontend variables (build-time)¶
Build-time only
React environment variables prefixed with REACT_APP_ are embedded in the
JavaScript bundle at docker build time. Changing them after the image is
built has no effect. Pass them as Docker Compose build.args.
| Variable | Default | Description |
|---|---|---|
REACT_APP_API_URL |
http://localhost:8000 |
Base URL of the backend API. In production, set this to the public URL of the backend (e.g. https://repod.example.com if Nginx proxies /api/ to the backend). If left empty (""), the frontend uses relative URLs and relies on the Nginx reverse proxy. |
REACT_APP_REPO_URL |
http://localhost:80 |
Base URL of the repository server shown to users in client setup instructions. |
Docker Compose variables (.env file)¶
These variables are interpolated by Docker Compose itself before launching containers.
Place them in a .env file next to docker-compose.yaml.
| Variable | Default | Description |
|---|---|---|
BIND_HOST |
0.0.0.0 |
Host interface to bind all published ports to. Set to 127.0.0.1 in production when a reverse proxy handles external traffic. |
BACKEND_PORT |
8000 |
Host port mapped to the backend container. |
FRONTEND_PORT |
3003 |
Host port mapped to the frontend container. |
APT_PORT / RPM_PORT |
80 |
Host port mapped to the repository Nginx container. |
REACT_APP_API_URL |
http://localhost:8000 |
Passed as a build argument to the frontend image. |
REACT_APP_REPO_URL |
http://localhost:80 |
Passed as a build argument to the frontend image. |
Example: production backend.env¶
backend.env
# ── Security ─────────────────────────────────────────────────────────────────
JWT_SECRET_KEY=a3f8c2e1d4b7a9f0e2c5d8b1a4f7e0c3d6b9a2f5e8c1d4b7a0f3e6c9d2b5a8f1
JWT_EXPIRE_MINUTES=60
ADMIN_USERNAME=admin
ADMIN_PASSWORD_HASH=$$2b$$12$$exampleHashHere...
# ── Environment ──────────────────────────────────────────────────────────────
ENV=production
APP_VERSION=v1.2.0
# ── Reverse proxy ────────────────────────────────────────────────────────────
TRUSTED_PROXIES=127.0.0.1,10.0.0.0/8
CORS_ORIGINS=https://repod.example.com
# ── LDAP (optional) ──────────────────────────────────────────────────────────
LDAP_URL=ldaps://dc.example.com:636
LDAP_BIND_DN=CN=repod-svc,OU=ServiceAccounts,DC=example,DC=com
LDAP_BIND_PASSWORD=service-account-password
LDAP_BASE_DN=OU=Users,DC=example,DC=com
LDAP_USER_ATTR=sAMAccountName
# ── SMTP (optional) ──────────────────────────────────────────────────────────
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASSWORD=smtp-password
SMTP_FROM=[email protected]