Contribute and deploy
Deploy the cache server
Deploy fluentci-cache with systemd, S3 or R2, a public CDN, account upload tokens, and owner storage management.
Build the standalone server
The cache lives in cache/ with its own Cargo manifest and lockfile. Build for
the target Linux architecture using Rust 1.90 or newer:
cargo build --release --locked --manifest-path cache/Cargo.toml
The binary is cache/target/release/fluentci-cache. This standalone build does
not need Studio assets or a build of the FluentCI CLI.
Configure S3 or R2 and the public CDN
Create the bucket before starting the service. For S3-compatible storage, the server writes with AWS credentials and reads anonymously through the public CDN. Grant the storage identity list, write, delete, and multipart upload/abort access to the selected bucket and prefix. Owner browsing and storage cleanup require list and delete permissions.
Configure /etc/fluentci/cache.env with mode 0600:
FLUENTCI_CACHE_BACKEND=s3
FLUENTCI_CACHE_BIND=127.0.0.1:8080
FLUENTCI_CACHE_BUCKET=your-bucket
FLUENTCI_CACHE_REGION=auto
FLUENTCI_CACHE_ENDPOINT=https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com
FLUENTCI_CACHE_CDN_URL=https://cache-cdn.fluentci.io
FLUENTCI_CACHE_PREFIX=fluentci-cache/v1
FLUENTCI_CACHE_PUBLIC_READ=true
AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
FLUENTCI_CACHE_TOKEN=YOUR_RANDOM_ADMIN_SECRET
FLUENTCI_CACHE_UPLOAD_TOKEN_PUBLIC_KEY_FILE=/etc/fluentci/cache-upload-public.pem
FLUENTCI_CACHE_UPLOAD_TOKEN_ISSUER=did:web:api.fluentci.io
RUST_LOG=fluentci_cache=info
This example targets R2. For AWS S3, omit the endpoint and use the bucket's AWS
region. Machine roles can replace static AWS credentials. Temporary credentials
also require AWS_SESSION_TOKEN.
Generate the administrator secret with openssl rand -hex 32. It controls
operations endpoints and legacy shared-cache access; keep it separate from user
upload tokens. The endpoint variable is FLUENTCI_CACHE_ENDPOINT.
The CDN URL points at the bucket root, before the configured storage prefix.
It must support GET, HEAD, byte ranges, and 404 responses for missing objects.
Never use the cache service's own URL as its read origin. For production,
cache.fluentci.io serves the cache while cache-cdn.fluentci.io serves R2.
Account objects map to:
<prefix>/accounts/<owner-did-sha256>/<protocol>/<key>
Client tokens and AWS credentials are not forwarded to the CDN. Reads do not fall back to authenticated S3. Configure revalidation or short cache lifetimes for mutable keys and disable negative caching. Uploads and origin deletions do not purge cached CDN responses. Direct CDN access remains public even if public reads are disabled on the cache server.
Generate account-token signing keys
Run this on a trusted server:
umask 077
openssl genpkey -algorithm ED25519 -out cache-upload-private.pem
openssl pkey -in cache-upload-private.pem -pubout -out cache-upload-public.pem
Install the private key only on the API server, readable by its fluentci
service account. In the API's /etc/fluentci/api.env, configure:
CACHE_PUBLIC_URL=https://cache.fluentci.io
CACHE_TOKEN_PRIVATE_KEY_FILE=/etc/fluentci/cache-upload-private.pem
Install the public key on the cache server, readable by fluentci-cache.
FLUENTCI_CACHE_UPLOAD_TOKEN_ISSUER must match the API's SERVICE_DID.
Restart both services after rotating keys. Cache servers with the new public key
reject tokens signed by the previous private key. These keys sign upload JWTs;
Nix narinfo uses its own signing keys.
Install the systemd service
From the checkout root, on Linux:
sudo useradd --system --user-group --home-dir /var/lib/fluentci-cache \
--shell /usr/sbin/nologin fluentci-cache
sudo install -d -m 0755 /etc/fluentci
sudo install -m 0755 cache/target/release/fluentci-cache /usr/local/bin/fluentci-cache
sudo install -m 0640 -o root -g fluentci-cache \
cache/cache.example.toml /etc/fluentci/cache.toml
sudo install -m 0600 systemd/fluentci-cache.env.example /etc/fluentci/cache.env
sudoedit /etc/fluentci/cache.toml /etc/fluentci/cache.env
sudo install -m 0644 systemd/fluentci-cache.service \
/etc/systemd/system/fluentci-cache.service
sudo systemd-analyze verify /etc/systemd/system/fluentci-cache.service
sudo systemctl daemon-reload
sudo systemctl enable --now fluentci-cache
sudo journalctl -u fluentci-cache -f
Set ownership and permissions on the public key to root:fluentci-cache and
0640. On the API host, use root:fluentci and 0640 for the private key.
Both service accounts need permission to traverse /etc/fluentci.
Settings resolve in this order: defaults, TOML, environment, explicit flags. The administrator token and S3/CDN configuration are required before starting a writable S3 server. Defaults allow uploads up to 10 GiB, 128 active transfers, and a 300-second transfer timeout. The unit allows 330 seconds for shutdown; increase that deadline if increasing the transfer timeout.
For a file backend, use FLUENTCI_CACHE_BACKEND=file and
FLUENTCI_CACHE_DIRECTORY=/var/lib/fluentci-cache/objects. Systemd creates the
writable state directory. Memory storage is temporary. There is no built-in TTL,
eviction policy, or quota; configure storage lifecycle policies separately.
Route HTTPS through Caddy
For a Caddy container using host networking, add this to its active Caddyfile:
cache.fluentci.io {
reverse_proxy 127.0.0.1:8080
}
The production path is /pds/caddy/etc/caddy/Caddyfile. Validate and reload:
docker exec caddy caddy validate --config /etc/caddy/Caddyfile
docker exec caddy caddy reload --config /etc/caddy/Caddyfile
The root returns the FluentCI Cache ASCII welcome message and documentation link. Keep the listener on loopback and let Caddy handle HTTPS.
Verify a deployment
curl --fail https://cache.fluentci.io/healthz
curl --fail -H "Authorization: Bearer $ADMIN_TOKEN" \
https://cache.fluentci.io/readyz
/healthz tests liveness. /readyz probes the storage and CDN but does not prove
write permissions. /metrics requires the administrator token when configured.
Verify an account-token PUT, an anonymous cache GET, a direct CDN GET, and owner
listing/deletion using a dedicated probe key. Remove that probe afterward.
Deploy the API changes and migrations as described in
registry deployment. Use the
cache page to generate account tokens and invite users.
For upgrades, stage a new binary as /usr/local/bin/fluentci-cache.new, rename
it over the installed binary, then restart fluentci-cache. Keep configuration,
keys, and persistent storage separate from the binary.