Ceryx logo
Menu
View as Markdown

Configuration

Every environment variable Ceryx reads, with its default and what it does.

Ceryx is configured with environment variables on its container. When using Compose, set them in the service's environment section. Compose can also read values from a .env file and pass them to the container through that section. Run docker compose up -d to apply changes.

An empty value counts as unset, so Ceryx uses the default.

Certificates

Variable Default Description
CERYX_DISABLE_LETS_ENCRYPT false Set to true to stop getting certificates from Let's Encrypt.
CERYX_LETS_ENCRYPT_CA https://acme-v02.api.letsencrypt.org/directory ACME directory to get certificates from, for example Let's Encrypt's staging environment while testing.
CERYX_TLS_DEFAULT_CERTIFICATE /etc/ceryx/ssl/default.crt Certificate for hostnames without one of their own. The default is self-signed. Ceryx 0.x's CERYX_SSL_DEFAULT_CERTIFICATE still works.
CERYX_TLS_DEFAULT_KEY /etc/ceryx/ssl/default.key Private key of the default certificate. Ceryx 0.x's CERYX_SSL_DEFAULT_KEY still works.

See How certificates work.

Route defaults

These apply when a route is created without the setting, and are stored with the route. Changing them later doesn't change existing routes.

Variable Default Description
CERYX_ROUTE_SETTINGS_DEFAULT_ENFORCE_HTTPS false enforce_https for new routes. Must be true or false.
CERYX_ROUTE_SETTINGS_DEFAULT_MTLS_REQUIRE_CLIENT_CERTIFICATE false mtls_require_client_certificate for new routes. Must be true or false.

mTLS

These apply to routes that require client certificates but don't set their own CA or depth. Ceryx reads them on every request, so changes apply to those routes right away.

Variable Default Description
CERYX_MTLS_DEFAULT_TRUSTED_CA None Path of the CA bundle, inside the container, that client certificates must be signed by.
CERYX_MTLS_DEFAULT_VERIFY_DEPTH OpenSSL's limit Maximum number of intermediate certificates between a client certificate and the CA.

See API protection with mTLS.

Proxying

Variable Default Description
CERYX_MAX_REQUEST_BODY_SIZE 100m Largest request body Ceryx accepts, in NGINX size units such as 10m or 1g. Larger requests get 413.
CERYX_DNS_RESOLVER 127.0.0.11 DNS server for resolving hostnames in targets. The default is Docker's, which resolves container names.

Storage

Variable Default Description
CERYX_STORAGE_BACKEND sqlite Storage backend for routes and certificates. Only sqlite is supported.
CERYX_SQLITE_PATH /var/lib/ceryx/db.sqlite Path of the SQLite database file. Keep it on a volume.
CERYX_SQLITE_WAL_MODE true Use SQLite's write-ahead log, so reads don't wait for writes.
CERYX_SQLITE_MMAP_SIZE 1073741824 Bytes of the database SQLite may memory-map for faster reads (1 GiB).
CERYX_SQLITE_POOL_MODE worker worker keeps a database connection open per NGINX worker. request opens one per request.

Debugging

Variable Default Description
CERYX_DEBUG false Turns on debug logs and turns off the Lua code cache. For development only.
CERYX_DOCKERIZE_EXTRA_ARGS None Extra arguments for dockerize, which renders Ceryx's NGINX configuration when the container starts.

Compose file

The production compose.yml reads these on the server, outside the container:

Variable Default Description
CERYX_EXTERNAL_HTTP_PORT 80 Port on the server for HTTP. Add an address to listen on one interface only, such as 10.0.0.5:80.
CERYX_EXTERNAL_HTTPS_PORT 443 Port on the server for HTTPS.
CERYX_NETWORK ceryx Name of the Docker network your services join.
IMAGE_NAME ghcr.io/withlogicco/ceryx Ceryx image to run.
IMAGE_TAG latest Image tag. Set it to stay on one version.

Ports

Port in the container Serves
80 HTTP, and Let's Encrypt's domain checks.
443 HTTPS, with HTTP/2.
8080 The API. It has no authentication, so don't publish it.
Esc

Type to search the docs.