Cache Service
Cache Service
The Crab cache service is a self-hosted acceleration layer for teams that work with large repositories, repeated hydrations, CI fleets, and shared binary data.
It helps reduce:
- Repeated object-store reads.
- Object-store request volume.
- Upload churn when pushed content overlaps with data already known by the organization.
The origin object store remains authoritative. If the cache service is unavailable, Crab falls back to normal origin reads and uploads.
When To Use It
Deploy the cache service when:
- Multiple developers clone, fetch, or hydrate the same large repositories.
- CI jobs repeatedly fetch the same data.
- Multiple repositories share datasets, model checkpoints, media, or build outputs.
- You want pushed content to become warm for the rest of the team immediately.
- You want a central operational point for cache metrics and capacity planning.
You usually do not need it for single-user workflows or small repositories.
What Users Get
| Capability | Outcome |
|---|---|
| Read-through cache | Repeated clones, fetches, and hydrates avoid repeated origin reads. |
| Push warming | Newly pushed data can be served from the cache immediately. |
| Shared dedup knowledge | Pushes can skip chunks the cache service already knows about. |
| Central metrics | Operators can track cache hit rate, bytes served, and origin miss behavior. |
Recommended Rollout
- Deploy one cache service near the object-store region.
- Use PSK authentication on a private network for the first rollout.
- Configure one test repository with
[cache].service_url. - Push data and verify cache warming.
- Clear a client local cache and verify hydrate or fetch reads through the service.
- Roll the config out to CI and developer machines.
- Use separate cache instances for environments or tenants that must not share dedup visibility.
Documentation Map
- Deployment: Docker, Kubernetes, and systemd deployment.
- Quickstart: start one service and connect one client.
- How It Works: request flow, data safety, and isolation model.
- Server Configuration: TOML reference.
- Client Configuration: Crab and CI configuration.
- Authentication: PSK, bearer, and proxy-terminated mTLS.
- Monitoring: health checks, metrics, dashboards, and alerts.
- Operations: sizing, scaling, upgrades, and recovery.
- Troubleshooting: symptom-first diagnostics.