# bouine

> Bouine is a cloud-native HTTP cache in Go - RFC9111 compliant, zero-alloc hit path, gossip clustering, no external K/V store.

- [Compare bouine](https://bouine.org/v0.4/compare/): Side-by-side comparison of bouine against Envoy, NGINX, HAProxy, Varnish, and Caddy — across DevOps, SRE, and Software Engineer criteria.
- [Documentation](https://bouine.org/v0.4/docs/): Complete user and contributor documentation for installing, configuring, operating, troubleshooting, and extending bouine safely.

## Compare bouine

> Side-by-side comparison of bouine against Envoy, NGINX, HAProxy, Varnish, and Caddy — across DevOps, SRE, and Software Engineer criteria.


## Documentation

> Complete user and contributor documentation for installing, configuring, operating, troubleshooting, and extending bouine safely.

- [Getting started](https://bouine.org/v0.4/docs/getting-started/): Install bouine, run it locally, cache your first response, deploy with Docker or Kubernetes, and adapt example configs.
- [Configuration](https://bouine.org/v0.4/docs/configuration/): Reference for bouine YAML configuration: listeners, storage, routes, cache policy, TLS, clustering, Helm chart values, and health checks.
- [Operations](https://bouine.org/v0.4/docs/operations/): Runbook for operating bouine: lifecycle, authentication, cache invalidation, monitoring, dashboard, Kubernetes ops, and troubleshooting.
- [Architecture](https://bouine.org/v0.4/docs/architecture/): How bouine is structured internally: listeners, pipeline, storage, cache engine, origin pools, clustering, and observability.
- [Guides](https://bouine.org/v0.4/docs/guides/): Step-by-step guides for migrating from Varnish or NGINX, integration patterns, and capacity planning.
- [Contributing](https://bouine.org/v0.4/docs/contributing/): Contributor guide covering local setup, development workflow, commit format, pull request checks, and project standards.
- [Reference](https://bouine.org/v0.4/docs/reference/): CLI, admin API, and response headers reference.
- [FAQ](https://bouine.org/v0.4/docs/faq/): Frequently asked questions about bouine.
- [Resources](https://bouine.org/v0.4/docs/resources/): Discover curated links to official docs, tools, templates, and learning materials that help you deepen your knowledge and get more from this project.

### Getting started

> Install bouine, run it locally, cache your first response, deploy with Docker or Kubernetes, and adapt example configs.

- [Install](https://bouine.org/v0.4/docs/getting-started/install/): Install bouine from Docker Hub, GitHub release binaries, or source, and understand requirements for each method.
- [Quick start](https://bouine.org/v0.4/docs/getting-started/first-cache/): Start a small origin server, put bouine in front of it, and verify MISS then HIT behavior through headers and metrics.
- [Docker](https://bouine.org/v0.4/docs/getting-started/docker/): Run the official bouine Docker image, mount custom configuration, and build fast multi-architecture images locally.
- [Kubernetes](https://bouine.org/v0.4/docs/getting-started/kubernetes/): Deploy bouine to Kubernetes with Helm, configure StatefulSet gossip, verify peer discovery, and perform rolling updates.
- [Example configurations](https://bouine.org/v0.4/docs/getting-started/examples/): Ready-to-adapt bouine YAML examples for static sites, self-served static files, API gateways, bouine-in-front-of-Cloudflare, and e-commerce routes.

### Configuration

> Reference for bouine YAML configuration: listeners, storage, routes, cache policy, TLS, clustering, Helm chart values, and health checks.

- [Cache policy](https://bouine.org/v0.4/docs/configuration/cache-policy/): Understand how bouine chooses TTLs, overrides them per-route, serves stale content, applies negative caching, jitters expirations, refreshes proactively before expiry, and builds cache keys.
- [Static file serving](https://bouine.org/v0.4/docs/configuration/static-files/): Serve files directly from a local directory without a separate origin server. Path traversal defense, MIME types, ETags, range requests, and optional cache integration.
- [Storage tiers](https://bouine.org/v0.4/docs/configuration/storage/): Understand bouine's hot and warm storage tiers, SIEVE eviction, capacity planning, and operational tuning.
- [TLS](https://bouine.org/v0.4/docs/configuration/tls/): Configure TLS termination with certificate management, SNI, and automatic reload.
- [Clustering](https://bouine.org/v0.4/docs/configuration/cluster-modes/): Configure bouine clustering: consistency modes, gossip membership, peer fetch, mTLS, invalidation propagation, and metrics.
- [Helm chart reference](https://bouine.org/v0.4/docs/configuration/helm/): All configurable values for the bouine Helm chart with defaults, descriptions, and production deployment tips.
- [Experimental features](https://bouine.org/v0.4/docs/configuration/experimental/): Opt-in experimental features that may become stable in future releases.

### Operations

> Runbook for operating bouine: lifecycle, authentication, cache invalidation, monitoring, dashboard, Kubernetes ops, and troubleshooting.

- [Lifecycle](https://bouine.org/v0.4/docs/operations/lifecycle/): Start, stop, and drain bouine in production and Kubernetes.
- [Authentication](https://bouine.org/v0.4/docs/operations/authentication/): Configure and retrieve the admin bearer token protecting all write endpoints.
- [Cache invalidation](https://bouine.org/v0.4/docs/operations/cache-invalidation/): Purge by URL, predicate ban, surrogate-key invalidation, and soft-purge refresh — and how they propagate across cluster peers.
- [Cluster consistency modes](https://bouine.org/v0.4/docs/operations/cluster-modes/): Verify, diagnose, and switch between strong and eventual cluster consistency modes.
- [Monitoring](https://bouine.org/v0.4/docs/operations/monitoring/): Prometheus metrics, access log fields, OpenTelemetry tracing, and admin API endpoints for observing bouine.
- [Dashboard](https://bouine.org/v0.4/docs/operations/dashboard/): Access the built-in operator dashboard for live cache metrics, route performance, cluster health, and one-click invalidation.
- [Kubernetes operations](https://bouine.org/v0.4/docs/operations/kubernetes/): Scale, update, and verify cluster health for bouine running on Kubernetes.
- [Observability guide](https://bouine.org/v0.4/docs/operations/observability/): End-to-end guide for wiring Prometheus, Loki, Tempo, and Grafana Alloy to collect metrics, logs, and traces from a bouine cluster.
- [Cloudflare CDN propagation](https://bouine.org/v0.4/docs/operations/cloudflare/): Forward bouine cache invalidation operations to Cloudflare's edge so both caches stay in sync.
- [Troubleshooting](https://bouine.org/v0.4/docs/operations/troubleshooting/): Troubleshoot common bouine production issues: cache misses, cluster problems, rolling restart failures, invalidation, and origin health.

### Architecture

> How bouine is structured internally: listeners, pipeline, storage, cache engine, origin pools, clustering, and observability.


### Guides

> Step-by-step guides for migrating from Varnish or NGINX, integration patterns, and capacity planning.

- [Migration from NGINX](https://bouine.org/v0.4/docs/guides/nginx-migration/): Migrate from NGINX proxy_cache to bouine by mapping directives, cache keys, stale serving, and observability concepts.
- [Migration from Varnish](https://bouine.org/v0.4/docs/guides/varnish-migration/): Complete migration guide from Varnish Cache to bouine: conceptual mapping, VCL vs YAML side-by-side, parity tables, behavioral differences, and FAQ.
- [Reverse proxy examples](https://bouine.org/v0.4/docs/guides/reverse-proxies/): Deploy bouine in front of Caddy, Traefik, HAProxy, and nginx with ready-to-adapt configuration examples.
- [Capacity planning](https://bouine.org/v0.4/docs/guides/capacity-planning/): Size bouine for your workload: estimate hot and warm tier capacity, choose cluster mode and replica count, and plan for growth.
- [Benchmarks](https://bouine.org/v0.4/docs/guides/benchmarks/): Benchmark methodology and results comparing bouine against Varnish, NGINX, and Envoy across cache hit, miss, and mixed workloads.
- [Production readiness checklist](https://bouine.org/v0.4/docs/guides/production-checklist/): Checklist to review before deploying bouine to production.
- [Service mesh compatibility](https://bouine.org/v0.4/docs/guides/service-mesh/): Run bouine alongside Istio, Linkerd, and Cilium service meshes.
- [Example Guide](https://bouine.org/v0.4/docs/guides/example/): Learn how to structure clear, task-focused guides that walk users through real workflows step by step, improving documentation usability and success.

### Contributing

> Contributor guide covering local setup, development workflow, commit format, pull request checks, and project standards.

- [Codebase guide](https://bouine.org/v0.4/docs/contributing/codebase/): Contributor-oriented map of bouine packages, layers, good first tasks, and rules for safely changing cache behavior.
- [Security](https://bouine.org/v0.4/docs/contributing/security/): Security reporting, supported scope, high-impact vulnerability classes, and operational hardening checklist for bouine.

### Reference

> CLI, admin API, and response headers reference.

- [CLI](https://bouine.org/v0.4/docs/reference/cli/): bouine command-line interface reference.
- [Admin API](https://bouine.org/v0.4/docs/reference/api/): Admin API endpoints, authentication, and response formats.
- [Response headers](https://bouine.org/v0.4/docs/reference/headers/): HTTP response headers added by bouine.
- [Go SDK](https://bouine.org/v0.4/docs/reference/go-sdk/): Use the bouine Go SDK to manage cache invalidation, check health, and inspect cluster peers programmatically.
- [Example Reference](https://bouine.org/v0.4/docs/reference/example/): Learn how to design concise, comprehensive reference pages that document concepts, options, and behavior clearly so users can quickly find exact answers.