Deployment

Deploy the cache service close to the object-store region and give it fast local storage. The cache is rebuildable, but a warm cache is valuable operationally, so use persistent SSD or NVMe storage.

Sizing

Start with:

Scale disk first. Most low hit-rate problems are caused by a cache that is smaller than the active working set.

Docker

Build:

docker build -f crab/deploy/cache-service/Dockerfile -t crab-cache-server:latest .

Run:

docker run -d \
  --name crab-cache \
  -p 8443:8443 \
  -v /data/crab-cache:/data/crab-cache \
  -v /etc/crab-cache-server:/etc/crab-cache-server:ro \
  --restart=unless-stopped \
  crab-cache-server:latest

Mount config.toml at /etc/crab-cache-server/config.toml.

Kubernetes

Use one pod per cache volume. A typical deployment uses:

• A Deployment with strategy.type = Recreate.
• A ReadWriteOnce persistent volume.
• A ClusterIP service or private load balancer.
• Readiness probe: /v1/health.
• Liveness probe: /v1/health/live.

Example probe configuration:

livenessProbe:
  httpGet:
    path: /v1/health/live
    port: 8443
  periodSeconds: 15

readinessProbe:
  httpGet:
    path: /v1/health
    port: 8443
  periodSeconds: 5

Use HTTP probes when TLS terminates before the pod. Use HTTPS probes when TLS terminates at the cache server.

systemd

For a VM or bare-metal host:

useradd -r -s /sbin/nologin -d /data/crab-cache crab-cache
mkdir -p /data/crab-cache /etc/crab-cache-server
chown -R crab-cache:crab-cache /data/crab-cache
install -m 0755 crab-cache-server /usr/local/bin/
install -m 0640 config.toml /etc/crab-cache-server/config.toml
install -m 0644 crab/deploy/cache-service/crab-cache-server.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now crab-cache-server

Check status:

systemctl status crab-cache-server
journalctl -u crab-cache-server -f

TLS And Proxies

Recommended production patterns:

• Terminate TLS at a load balancer, ingress, or service mesh.
• Keep the cache service on a private network.
• For mTLS, validate certificates at the proxy or mesh and forward the validated identity.
• Do not expose bearer mode or plaintext PSK traffic to untrusted networks.

Smoke Test

curl -fsS http://localhost:8443/v1/health/live
curl -fsS http://localhost:8443/v1/health
curl -fsS http://localhost:8443/v1/metrics | head
curl -i http://localhost:8443/v1/admin/stats
curl -i -H "X-Cache-PSK: $CRAB_CACHE_PSK" \
  http://localhost:8443/v1/admin/stats

Expected:

• Liveness returns ok.
• Readiness returns ok when origin is reachable.
• Metrics are available.
• Admin endpoints reject missing auth.
• Admin endpoints accept valid auth.

Then configure one Crab client and run a real push or hydrate.