Installation
Configuration reference
Every environment variable the Relic server and worker read.
Relic reads its configuration from environment variables. relic server start, relic server worker and relic server migrate take --settings <file>, which first sets the variables of a file of KEY=value lines,
replacing ones already set; give the server and the worker the same file. Blank
lines and lines starting with # are skipped, and quotes around a value are
dropped. A line with export, or with spaces around =, stops the command with
an error that names the line.
Durations use Go syntax (90s, 10m, 336h). Switches take true or
false. Feed URLs take an http or https URL, or off. If any variable is
wrong, Relic refuses to start and lists every error.
Core
| Variable | Default | Meaning |
|---|---|---|
RELIC_HTTP_LISTEN_ADDRESS | :8090 | Listen address, host:port or :port. Serves HTTPS unless the server runs with --no-tls. |
RELIC_DATABASE_URL | (required) | A PostgreSQL URL, such as postgres://relic:<password>@db:5432/relic?sslmode=require, or a SQLite file for a single node, such as sqlite:///var/lib/relic/data/relic.db (Single node). |
RELIC_ADMIN_USERNAME, RELIC_ADMIN_PASSWORD | admin, (none) | The first administrator, created when no user exists. The password needs at least 8 characters, as every user password does. |
RELIC_ENCRYPTION_KEY | (none) | 32 bytes in base64 (openssl rand -base64 32). Seals token signing keys, signing key pairs, and the upstream, replication and LDAP manager passwords. See Secrets at rest. |
RELIC_UPSTREAM_ALLOW_PRIVATE_ADDRESSES | false | true lets remote repositories and replication reach loopback, private and link-local addresses. |
RELIC_UPSTREAM_CA_CERTIFICATE_FILE | (none) | A PEM file of extra CA certificates, trusted besides the system roots, for the servers remote repositories and replication connect to. Set it on the server and the worker. See Trusting the authority. |
RELIC_WEBHOOK_ALLOW_PRIVATE_ADDRESSES | false | true lets webhooks reach loopback, private and link-local addresses. |
TLS
relic server start serves HTTPS: TLS 1.3 (with the hybrid post-quantum
X25519MLKEM768 key exchange), and TLS 1.2 with ECDHE and AES-GCM or
ChaCha20-Poly1305 only. Older versions and CBC suites are refused.
relic server start --no-tls serves plain HTTP, for use behind a proxy that
terminates TLS. List that proxy in RELIC_TRUSTED_PROXIES
(Behind a reverse proxy). The
metrics listener always serves plain HTTP.
| Variable | Default | Meaning |
|---|---|---|
RELIC_TLS_CERTIFICATE_FILE, RELIC_TLS_KEY_FILE | (none) | Your certificate chain and private key, as PEM files. Set both or neither. Reloaded when either changes; a pair that does not load is logged as a warning and the previous certificate stays in use. |
RELIC_TLS_DIRECTORY | $XDG_CONFIG_HOME/relic/tls, or ~/.config/relic/tls; /etc/relic/tls in the image | Where Relic keeps the certificate authority and certificate it generates when you give it none. |
RELIC_TLS_MIN_VERSION | 1.2 | 1.2 or 1.3. |
RELIC_TLS_HOSTNAMES | (none) | Comma-separated host names (*. allowed in front) and IP addresses to add to the generated certificate. |
The generated certificate authority
Without your own certificate, Relic creates these files in
RELIC_TLS_DIRECTORY:
| File | Holds |
|---|---|
ca.crt, ca.key | A certificate authority, valid for 10 years. The key has mode 0600. |
server.crt, server.key | The server certificate, valid for 90 days. Relic issues a new one at every start and 30 days before it expires. |
The keys are ECDSA P-384. The server certificate holds localhost,
127.0.0.1, ::1, the host name, the interface addresses, the host of
RELIC_HTTP_LISTEN_ADDRESS and RELIC_TLS_HOSTNAMES. Add the name clients
use, such as relic.example.com, to RELIC_TLS_HOSTNAMES.
At start, the server logs the path of ca.crt and its SHA-256 fingerprint.
Give clients ca.crt; keep ca.key on the server. Keep the directory across
restarts and upgrades: if it is lost, Relic creates a new authority that every
client has to trust again.
Each server creates its own authority. Behind one load balancer, give every
server the same RELIC_TLS_CERTIFICATE_FILE and RELIC_TLS_KEY_FILE.
Trusting the authority
Clients need a private authority's certificate:
| Client | Where the certificate goes |
|---|---|
| relic CLI | --ca-file ca.crt on relic auth login, or accept the fingerprint it shows (Sign in). |
| Browsers and other tools | The operating system's trust store. |
| npm | cafile in .npmrc. |
| pip | --cert ca.crt, or PIP_CERT. |
| Go | SSL_CERT_FILE. |
| Docker | /etc/docker/certs.d/<host:port>/ca.crt on each machine that pushes or pulls. |
| Maven, Gradle | The JVM trust store. |
| Another Relic server (remote repositories, replication) | RELIC_UPSTREAM_CA_CERTIFICATE_FILE on the server and the worker. |
Object storage
See Storage for each provider.
| Variable | Default | Meaning |
|---|---|---|
RELIC_OBJECT_STORAGE_TYPE | s3 | s3 (Amazon S3 or S3-compatible), azure, gcs, or filesystem (a local directory). |
RELIC_OBJECT_STORAGE_PATH | (required with filesystem) | Absolute path of the content directory, such as /var/lib/relic/objects. |
RELIC_OBJECT_STORAGE_ENDPOINT | (empty) | s3: the service's base URL with scheme, such as http://seaweedfs-s3:8333; empty for Amazon S3. azure: https://<account>.blob.core.windows.net. gcs: an emulator's URL only. |
RELIC_OBJECT_STORAGE_REGION | us-east-1 | The region Relic signs S3 requests for. |
RELIC_OBJECT_STORAGE_ACCESS_KEY, RELIC_OBJECT_STORAGE_SECRET_KEY | (empty) | A static S3 key pair. Empty uses the AWS default credentials (IRSA, EKS Pod Identity, the instance or task role, the environment). |
RELIC_OBJECT_STORAGE_SSE | (empty) | S3 server-side encryption for every write: AES256 or aws:kms. |
RELIC_OBJECT_STORAGE_SSE_KMS_KEY_ID | (empty) | The KMS key for aws:kms; empty uses the account's default key. |
RELIC_OBJECT_STORAGE_STORAGE_CLASS | (empty) | The S3 storage class for every write, such as INTELLIGENT_TIERING. |
RELIC_OBJECT_STORAGE_AZURE_CONNECTION_STRING | (empty) | azure: a connection string with the account key. Empty uses the default Azure credential. |
RELIC_OBJECT_STORAGE_ARTIFACTS_BUCKET | artifacts | The bucket, or Azure container, for content. |
RELIC_OBJECT_STORAGE_TEMPORARY_BUCKET | temporary | The bucket for uploads in progress. Must differ from the artifacts bucket. |
RELIC_OBJECT_STORAGE_CHECKSUM | when_supported | when_supported sends a checksum with every upload. when_required sends one only where S3 requires it, for services that reject uploads with XAmzContentSHA256Mismatch or another checksum error. |
Server
| Variable | Default | Meaning |
|---|---|---|
RELIC_MAX_CONNECTIONS | 8192 | Client connections accepted at once; more wait. 0 removes the cap. |
RELIC_MAX_UPLOAD_SIZE | (none) | The largest file Relic accepts, in bytes or with KiB, MiB, GiB or TiB (10GiB). Larger uploads fail with 413. A local repository can set a lower limit. |
RELIC_DATABASE_MAX_CONNECTIONS | 20 | PostgreSQL only. Connections per server or worker process. Processes times this value must fit within PostgreSQL's max_connections. pool_max_conns in RELIC_DATABASE_URL takes precedence. |
RELIC_DATABASE_STATEMENT_TIMEOUT | 5m | PostgreSQL only. The longest a server query may run; 0 removes the limit. Migrations and the worker have none. |
RELIC_FAILED_SIGN_INS_BEFORE_BACKOFF | 20 | Failed password attempts a client address may make within ten minutes. After that, Relic answers 429 until a wait passes: one second, doubling up to five minutes. Clients behind one NAT share the count. |
RELIC_TRUSTED_PROXIES | (none) | Comma-separated CIDRs or addresses of the proxies allowed to set X-Forwarded-For and X-Forwarded-Proto. |
RELIC_SIGN_IN_NOTE | (none) | Public text shown under the sign-in form. |
RELIC_LDAP_CA_CERTIFICATE_FILE | (none) | A PEM file of extra CA certificates for LDAP over ldaps:// or StartTLS. See LDAP. |
RELIC_TRASH_ENABLED | true | false makes deletes permanent. |
RELIC_INDEXER_DIR | share/relic/indexer beside the binary's directory; /usr/local/share/relic/indexer in the image | relic-indexer-<os>-<arch> builds that clients download. |
Worker
| Variable | Default | Meaning |
|---|---|---|
RELIC_TRASH_RETENTION | 336h | How long deleted items stay in the trash can. |
RELIC_AUDIT_RETENTION | 8760h | How long audit events are kept. |
RELIC_GARBAGE_COLLECTION_INTERVAL | 10m | How often garbage collection runs. |
RELIC_GARBAGE_COLLECTION_GRACE_PERIOD | 1h | How long unreferenced content is kept before deletion. Keep it longer than your longest backup copy (Backup). |
RELIC_SCAN_SYFT_PATH, RELIC_SCAN_GRYPE_PATH | syft, grype | The scanner binaries. If either is missing, Relic Scan is off. |
RELIC_SCAN_MEMORY_BUDGET | half the container's memory limit, at most 1GiB; 1GiB without a limit | The memory the scanner subprocesses share, in bytes or with KiB, MiB, GiB or TiB (768MiB). See Memory. |
RELIC_SCAN_GITLEAKS_PATH | gitleaks on PATH | The secrets analyzer; off when not found. |
RELIC_SCAN_TRIVY_PATH | trivy on PATH | The misconfiguration analyzer, run with its bundled checks and no downloads; off when not found. |
RELIC_SCAN_SCANCODE_PATH | (none) | ScanCode's scancode, for deep license scanning of file text. Slow, so off unless set. |
RELIC_SCAN_VULNERABILITY_DATABASE_DIR | /var/lib/relic/grype | Grype's vulnerability database. Keep it on a persistent volume. |
RELIC_SCAN_VULNERABILITY_DATABASE_URL | Grype's listing | A latest.json listing, such as a mirror of https://grype.anchore.io/databases/v6/latest.json. With off, import databases with relic security database import or on the System page; until then, scans fail, including jf scan and relic security scan. Stored artifacts are scanned again after an import. |
RELIC_SCAN_MAVEN_URL | off | A Maven repository Syft reads POMs from, for licenses and parent POMs. See Package lookups. |
RELIC_SCAN_PYPI_URL | off | A PyPI JSON API (<url>/<name>/<version>/json) Syft reads licenses from. |
RELIC_SCAN_NPM_URL | off | An npm registry (<url>/<name>/<version>) Syft reads licenses from. |
RELIC_SCAN_GO_PROXY_URL | off | One Go module proxy (<url>/<module>/@v/<version>.zip) Syft reads licenses from. |
RELIC_MALICIOUS_PACKAGES_URL | OSV's bucket | Malicious-package advisories, read from <url>/<ecosystem>/all.zip. |
RELIC_SCAN_GOVULNCHECK_PATH | govulncheck on PATH | Tells whether Go executables call the vulnerable code. Without it, Go findings have unknown reachability. |
RELIC_SCAN_GO_VULNERABILITY_DATABASE_URL | https://vuln.go.dev/vulndb.zip | The Go vulnerability database govulncheck reads. |
RELIC_END_OF_LIFE_URL | endoflife.date | endoflife.date's full product dump (/api/v1/products/full), read daily. With off, use relic security end-of-life import. |
RELIC_SECRET_VALIDATION_ENABLED | false | true sends each secret found in content to its provider (GitHub, GitLab, Slack, npm, Stripe) to check whether it is still valid. |
RELIC_SECRET_VALIDATION_PROVIDERS | all | Comma-separated: github, gitlab, slack, npm, stripe. |
RELIC_DEPS_DEV_URL | off | deps.dev's API (https://api.deps.dev) or a mirror, to flag deprecated and unmaintained packages. Each check sends a package name and version. |
RELIC_CVE_EPSS_URL | FIRST's daily EPSS scores | EPSS scores (.csv.gz). |
RELIC_CVE_KEV_URL | CISA's KEV catalog | The Known Exploited Vulnerabilities catalog (JSON). |
RELIC_CVE_RECORDS_URL | https://cveawg.mitre.org/api/cve | Serves CVE JSON 5 records at <url>/<CVE-ID>. |
In an air-gapped network, point the feeds at mirrors or set them to off.
Telemetry
The server and the worker both read these. See Monitoring.
| Variable | Default | Meaning |
|---|---|---|
RELIC_METRICS_LISTEN_ADDRESS | :8091 | Serves /metrics over plain HTTP, or off. |
RELIC_PROFILING_ENABLED | false | true adds /debug/pprof/ to the metrics listener. |
RELIC_METRICS_REPOSITORY_LABEL | false | true labels artifact, upstream, cache and replication series with the repository name. Series then grow with the number of repositories. |
RELIC_LOG_LEVEL | info | debug, info, warn or error. |
RELIC_LOG_FORMAT | json | json or text. |
OTEL_EXPORTER_OTLP_ENDPOINT | (none) | The OTLP/HTTP base URL, such as http://collector:4318. Without it or a traces endpoint, tracing is off. |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT | (none) | Full URLs per signal. |
OTEL_EXPORTER_OTLP_PROTOCOL | http/protobuf | The only protocol. Relic refuses to start with grpc. |
OTEL_EXPORTER_OTLP_HEADERS | (none) | Headers for the collector. |
OTEL_SERVICE_NAME | relic-server, relic-worker | The service name. |
OTEL_RESOURCE_ATTRIBUTES | (none) | Extra resource attributes, key=value,…. |
OTEL_TRACES_SAMPLER, OTEL_TRACES_SAMPLER_ARG | parentbased_always_on | always_on, always_off, traceidratio, or their parentbased_ forms; the argument is the ratio. |
OTEL_TRACES_EXPORTER | otlp | none turns tracing off. |
OTEL_LOGS_EXPORTER | none | otlp also sends log records to the collector. |
OTEL_SDK_DISABLED | false | true turns traces and OTLP logs off. |