Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Server Configuration

cellerd reads its configuration from a TOML file. It uses the file given with -f/--config. Without that flag, it reads $XDG_CONFIG_HOME/celler/server.toml (usually ~/.config/celler/server.toml).

On NixOS, you don’t write this file yourself. The services.cellerd.settings option generates it, using the same names as below. See Deploying to NixOS.

To check a configuration file without starting the server, run:

$ cellerd -f server.toml --mode check-config

Unknown options at the top level are rejected, so typos are caught early.

Minimal Example

[database]
url = "sqlite:///var/lib/cellerd/server.db?mode=rwc"

[storage]
type = "local"
path = "/var/lib/cellerd/storage"

[jwt]
rs256-public-key-file = "/etc/cellerd/public-key.pem"

The sections [database], [storage], and [jwt] are required. Everything else is optional.

Top-Level Options

OptionTypeDefaultDescription
listenstring"[::]:8080"Address and port to listen on. The --listen command-line flag overrides it.
allowed-hostslist of strings[] (all allowed)Accepted values of the HTTP Host header. Set this in production.
api-endpointstringderived from the Host headerPublic URL of the API, shown to clients. Must end with /, e.g. "https://cache.example.com/". Set this in production.
substituter-endpointstringsame as api-endpointPublic URL of the binary cache that Nix downloads from, if different from api-endpoint.
soft-delete-cachesboolfalseMark deleted caches as deleted instead of removing them from the database. The names of soft-deleted caches can’t be reused.
require-proof-of-possessionbooltrueRequire clients to upload the full data even if the server already has it. See Security Model.
max-nar-info-sizeinteger (bytes)1048576 (1 MiB)Maximum size of the metadata a client sends with an upload.

Warning

If allowed-hosts and api-endpoint are not set, the server trusts the Host header that clients send. Behind a reverse proxy, set both to your public hostname and URL.

[database]

OptionTypeDefaultDescription
urlstringrequiredDatabase connection URL. See below.
heartbeatboolfalseSend a query to the database every minute to keep the connection alive.

Celler supports SQLite and PostgreSQL:

# SQLite. mode=rwc creates the file if it doesn't exist.
url = "sqlite:///var/lib/cellerd/server.db?mode=rwc"

# PostgreSQL over a Unix socket
url = "postgresql:///cellerd?host=/run/postgresql"

# PostgreSQL over TCP
url = "postgresql://user:password@db.example.com/cellerd"

SQLite is enough for a single server. Use PostgreSQL if you run several API servers.

[storage]

Where Celler stores the cached data. The type option selects the storage backend.

Local Storage

OptionTypeDefaultDescription
typestring"local"
pathstringrequiredDirectory to store files in.
[storage]
type = "local"
path = "/var/lib/cellerd/storage"

S3 Storage

Works with Amazon S3 and S3-compatible services, such as Garage, MinIO, Cloudflare R2, and Backblaze B2.

OptionTypeDefaultDescription
typestring"s3"
regionstringrequiredThe region of the bucket.
bucketstringrequiredThe name of the bucket.
endpointstringAWSURL of the S3 service. Set this for anything other than Amazon S3.
credentials.access_key_idstringfrom environmentAccess key ID.
credentials.secret_access_keystringfrom environmentSecret access key.
[storage]
type = "s3"
region = "us-east-1"
bucket = "my-celler-bucket"
endpoint = "https://s3.example.com"

If you leave out credentials, Celler reads them from the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables. This keeps secrets out of the configuration file. On NixOS, put them in the file set by services.cellerd.environmentFile.

Note that the option names under credentials use underscores, unlike the other options.

To use an endpoint over plain http://, set the environment variable AWS_ALLOW_HTTP=true.

[jwt]

How the server checks the tokens that clients send. Set exactly one of rs256-public-key-file and hs256-secret-key-file.

OptionTypeDefaultDescription
rs256-public-key-filepathPEM file with an RSA public key. Tokens must be signed with the matching private key.
hs256-secret-key-filepathFile with a shared secret (raw bytes, not Base64). Tokens must be signed with the same secret.
token-bound-issuerstringnoneIf set, tokens must have this iss (issuer) claim.
token-bound-audienceslist of stringsnoneIf set, tokens must have an aud (audience) claim that contains one of these values.

RS256 is recommended: the server only has the public key, so a compromised server can’t be used to create new tokens. Create tokens with celler admin make-token and the matching private key or secret.

[chunking]

How uploaded NARs are split into chunks for deduplication. Without this section, chunking is disabled. For recommended values and trade-offs, see Chunking.

All values are in bytes. If the section is present, all four options are required.

OptionDescription
nar-size-thresholdOnly chunk NARs that are at least this large. 0 disables chunking; 1 chunks all NARs.
min-sizePreferred minimum chunk size.
avg-sizePreferred average chunk size.
max-sizePreferred maximum chunk size.

Changes only affect new uploads.

[compression]

How chunks are compressed in storage.

OptionTypeDefaultDescription
typestring"zstd"One of "none", "zstd", "brotli", "xz".
levelintegerdepends on typeCompression level. Defaults: zstd 8, brotli 5, xz 2.

Changing the compression only affects new uploads. After changing type, new uploads don’t reuse chunks stored with the old type, so deduplication is worse for a while.

[garbage-collection]

OptionTypeDefaultDescription
intervalduration"12 hours"How often to run garbage collection. "0s" disables automatic runs; you can still run cellerd --mode garbage-collector-once.
default-retention-periodduration"0s" (keep forever)Delete store paths that were neither uploaded nor downloaded for this long. Caches can override it with celler cache configure --retention-period.

Durations are strings like "30s", "12 hours", "3 months", or "1y".

Full Example

listen = "[::]:8080"
allowed-hosts = ["cache.example.com"]
api-endpoint = "https://cache.example.com/"

[database]
url = "postgresql:///cellerd?host=/run/postgresql"

[storage]
type = "s3"
region = "auto"
bucket = "celler"
endpoint = "https://<account-id>.r2.cloudflarestorage.com"

[jwt]
rs256-public-key-file = "/etc/cellerd/public-key.pem"

[chunking]
nar-size-threshold = 4194304  # 4 MiB
min-size = 2097152            # 2 MiB
avg-size = 8388608            # 8 MiB
max-size = 16777216           # 16 MiB

[compression]
type = "zstd"

[garbage-collection]
interval = "12 hours"
default-retention-period = "3 months"