# 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](/docs/concepts/certificates).

## 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](/docs/use-cases/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. |

> [!NOTE] Redis is not supported
> Ceryx stores routes and certificates in SQLite. The Redis backend is not supported.

## 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](/docs/api). It has no authentication, so don't publish it. |