bouine

Install

Mon, 01 Jan 0001 00:00:00 +0000

Docker

The fastest way to run bouine is the Docker image:

docker pull bouinecache/bouine:latest
docker run --rm -p 8080:80 -p 9000:9000 bouinecache/bouine:latest

The default image includes a minimal config at /etc/bouine/config.yaml so the container starts without a volume mount.

Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Starting bouine

bouine serve --config /etc/bouine/config.yaml --log-format json

On Kubernetes the StatefulSet container runs this command via the Helm chart (see deploy/helm/bouine/templates/statefulset.yaml). The --log-format json flag ensures structured logging for aggregation.

Migration from NGINX

Mon, 01 Jan 0001 00:00:00 +0000

Directive mapping

NGINX directive	bouine config	Notes
`proxy_cache_path ... max_size=1g`	`storage.hot_max_bytes: 1GiB`	bouine uses in-RAM storage, no filesystem levels
`proxy_cache_path ... keys_zone=api:10m`	Not needed	bouine manages shard count automatically (`N=NumCPU`)
`proxy_cache_valid 200 60s`	`routes[].cache.ttl_default: 60s`	Per-route, respects `Cache-Control` by default
`proxy_cache_valid 404 10s`	`routes[].cache.negative_ttl: 10s`	Negative caching for error responses
`proxy_cache_use_stale error http_500 http_502 http_503 http_504`	`routes[].cache.stale_if_error: 30s`	Serves stale on origin 5xx or timeout
`proxy_cache_background_update on`	`routes[].cache.stale_while_revalidate: 10s`	Background revalidation while serving stale
`proxy_cache_revalidate on`	Built-in	Conditional requests (`If-None-Match`, `If-Modified-Since`)
`proxy_cache_key $scheme$host$request_uri`	Automatic	xxhash128 of scheme+host+path+sorted query
`proxy_cache_key $scheme$host$request_uri$http_accept`	`cache.key.include_headers: [Accept]`	Explicit header keying
`proxy_ignore_headers Vary`	`cache.key.include_headers: [...]`	Explicit header keying instead of Vary
`proxy_no_cache $variable`	`routes[].cache.enabled: false`	Per-route disable
`proxy_cache_bypass $variable`	Not needed	Use route matching to separate cached/uncached
`proxy_cache_lock on`	Built-in (request collapsing)	Single-flight per cache key
`proxy_cache_lock_timeout 5s`	Built-in	Subscribers wait for leader fetch
`proxy_cache_min_uses 3`	Not needed	bouine caches on first response (RFC 9111)
`add_header X-Cache-Status $upstream_cache_status`	Built-in	`X-Cache` header (HIT, MISS, STALE, BYPASS, REVALIDATED)
`proxy_next_upstream error timeout`	`upstream_pools[].health.passive`	Passive health checks with outlier ejection

Key differences

No zone configuration — bouine manages memory automatically with SIEVE eviction
No filesystem cache — bouine uses in-RAM hot tier + mmap warm tier (no proxy_cache_path on disk)
Clustering built-in — NGINX requires third-party modules for cache sharing; bouine has gossip + peer fetch
RFC 9111 native — bouine implements the spec directly, not via directives
Observability built-in — Prometheus /metrics, structured JSON access logs with cache_status
No proxy_pass needed — upstream pools are declared separately and referenced by name in routes
Declarative config — no if blocks, no map directives, no embedded Lua

Example: API gateway

NGINX:

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

All write endpoints require Authorization: Bearer <token>. The token is resolved in priority order:

BOUINE_ADMIN_TOKEN environment variable (recommended for Kubernetes / Vault injection)
admin.token in the config file
Auto-generated random token (logged as WARN at startup)

Environment variable

Set BOUINE_ADMIN_TOKEN to inject the token without baking it into the config ConfigMap:

Cache policy

Mon, 01 Jan 0001 00:00:00 +0000

TTL selection

bouine picks freshness in this order:

CDN-Cache-Control (RFC 9211 targeted header — overrides Cache-Control for shared caches)
s-maxage
max-age
Expires (valid dates only; syntactically invalid Expires values are ignored)
Route ttl_default (operator fallback when origin sends no freshness)
Heuristic freshness from Last-Modified (10% of Date − Last-Modified, where allowed by status code)

If the route has ttl_override set, its value replaces the result of this waterfall entirely. See TTL override below.

Codebase guide

Mon, 01 Jan 0001 00:00:00 +0000

Package map

Package	Layer	Purpose
`internal/server`	L1	HTTP/1.1, TLS, route matching
`internal/storage`	L2	Hot store, warm tier, WAL, SIEVE
`internal/cache`	L3	RFC 9111 state machine and handler
`internal/origin`	L4	Upstream pools, health checks, hedged transport
`internal/cluster`	L5	memberlist gossip, hash ring, peer fetch
`internal/admin`	L6	Admin HTTP API
`internal/observability`	L7	Metrics, logs, access log

Migration from Varnish

Mon, 01 Jan 0001 00:00:00 +0000

Status: Stable for production use. Assumes familiarity with VCL and bouine’s YAML configuration model.

Quick reference

Varnish concept	bouine equivalent	Notes
VCL subroutines	declarative YAML config	bouine uses config, not code
`vcl_recv`	`routes[].match`	routing and request matching
`vcl_hash`	automatic cache key (`xxhash64`)	scheme + host + path + query + method
`vcl_backend_fetch`	`upstream_pools[]`	backend pool config
`vcl_backend_response`	origin `Cache-Control`	bouine honors RFC 9111 strictly
`beresp.ttl`	`cache.ttl_default`	overridden by origin headers
`beresp.grace`	`cache.stale_while_revalidate`	SWR semantics
`ban()`	admin API `POST /v1/ban`	HTTP-based invalidation API
`purge`	admin API `POST /v1/purge`	exact-match invalidation
Varnish log (`-g request`)	structured JSON logs (stdout)	pipe to any log aggregator
`varnishstat`	`/metrics` (Prometheus)	Prometheus-compatible metrics
VSM/shared memory	in-process memory	no mmap, no VSM files

1. Conceptual mapping

The big picture

Varnish is a programmable cache — you write VCL to define cache behavior. bouine is a declarative cache — you write YAML to describe routes, backends, and cache policies, and bouine implements RFC 9111 rigorously.

Quick start

Mon, 01 Jan 0001 00:00:00 +0000

Start a tiny origin server:

mkdir -p /tmp/bouine-origin
printf 'hello from origin\n' > /tmp/bouine-origin/index.html
python3 -m http.server 3000 --directory /tmp/bouine-origin

Create config.yaml:

listen:
 http: ":8080"
 admin: ":9000"

storage:
 hot_max_bytes: 256Mo

upstream_pools:
 - name: origin
 targets: ["127.0.0.1:3000"]

routes:
 - match: { path_prefix: / }
 pool: origin
 cache:
 ttl_default: 60s
 stale_while_revalidate: 10s
 stale_if_error: 300s

Run bouine:

Reverse proxy examples

Mon, 01 Jan 0001 00:00:00 +0000

bouine in front of Caddy

Caddy typically serves static files or acts as a reverse proxy itself. Deploy bouine in front of Caddy to add caching without modifying Caddy’s config.

Cache invalidation

Mon, 01 Jan 0001 00:00:00 +0000

Purge (exact URL)

# CLI
bouine purge https://example.com/products/123 --token <token>

# API
curl -X POST http://127.0.0.1:9000/v1/purge \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{"url":"https://example.com/products/123"}'

In a cluster, the purge is forwarded to all live peers via HTTP fan-out (in strong mode) or gossiped via the memberlist broadcast queue (in eventual mode).

Cluster consistency modes

Mon, 01 Jan 0001 00:00:00 +0000

Verify your mode

# Prometheus metric: always 1 with the mode label.
curl -s http://127.0.0.1:9000/metrics | grep bouine_cluster_mode_info

# Admin API: /v1/cluster/peers returns all members in every mode.
curl -s http://127.0.0.1:9000/v1/cluster/peers \
 -H "Authorization: Bearer ${BOUINE_ADMIN_TOKEN}"

# CLI
bouine cluster peers --server 127.0.0.1:9000 --token "${BOUINE_ADMIN_TOKEN}"

Expected: every node reports the same mode label. If they disagree, the cluster has a configuration drift — every pod must use the same mode.

Docker

Mon, 01 Jan 0001 00:00:00 +0000

Run the official image

docker run --rm \
 -p 8080:80 \
 -p 9000:9000 \
 bouinecache/bouine:latest

Mount a config file

docker run --rm \
 -p 8080:80 \
 -p 9000:9000 \
 -v "$PWD/config.yaml:/etc/bouine/config.yaml:ro" \
 bouinecache/bouine:latest

Build locally

On Apple Silicon targeting a Linux amd64 cluster:

Security

Mon, 01 Jan 0001 00:00:00 +0000

Report security issues via GitHub’s Private vulnerability reporting — it creates a tracked, embargoed advisory. No security email alias is published.

Scope

bouine binary
Helm chart
Container image
Go SDK

Examples of high-impact issues

Cache poisoning that leaks one user’s response to another
HTTP request smuggling through the data plane
Admin API authentication bypass
Peer impersonation in cluster mode
Path traversal in warm-tier storage

Hardening checklist

Keep admin port private; expose only through internal network or mTLS.
Use TLS verification for upstreams.
Run containers as non-root.
Use NetworkPolicy for cluster and admin ports.
Monitor purge/ban rates for misuse.
Do not log request/response bodies or credentials.

Static file serving

Mon, 01 Jan 0001 00:00:00 +0000

Overview

A route can serve files from a local directory instead of proxying to an upstream pool. This eliminates the need for a separate origin server (nginx, Caddy) when the content is already on the same machine as bouine — useful for single-node CDN edges, sidecar deployments, and static asset routes.

Storage tiers

Mon, 01 Jan 0001 00:00:00 +0000

bouine uses a two-tier storage architecture: a fast in-memory hot tier and an optional disk-backed warm tier.

Hot tier (RAM)

The primary cache store. Every cache hit is served from here.

Capacity planning

Mon, 01 Jan 0001 00:00:00 +0000

Step 1: Estimate your working set

The working set is the total size of responses that need to stay cached for acceptable hit rates.

working_set ≈ unique_cacheable_urls × avg_response_size

Workload	Typical working set
REST API (100k endpoints, 2 KiB avg)	~200 MiB
E-commerce catalog (1M products, 5 KiB avg)	~5 GiB
Static site / CDN (50k assets, 50 KiB avg)	~2.5 GiB
Media-heavy site (10k pages, 200 KiB avg)	~2 GiB

If you cannot estimate, start with 2 GiB and monitor bouine_hot_store_bytes / bouine_hot_store_max_bytes. If it stays above 0.9 consistently, double hot_max_bytes.

Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Add the chart repository

bouine publishes a Helm chart repository at https://charts.bouine.org, indexed on Artifact Hub. The chart pulls the bouinecache/bouine image from Docker Hub by default.

helm repo add bouine https://charts.bouine.org
helm repo update
helm search repo bouine

NAME CHART VERSION APP VERSION DESCRIPTION
bouine/bouine 0.1.0 0.1.0 Cloud-native HTTP cache in Go ...

Helm quickstart

helm install bouine bouine/bouine \
 --namespace bouine --create-namespace \
 --set "config.upstream_pools[0].name=app" \
 --set "config.upstream_pools[0].targets[0]=app.default.svc:8080" \
 --set "config.routes[0].pool=app"

This deploys a StatefulSet with gossip clustering, a headless Service for peer discovery, and a PodDisruptionBudget.

Monitoring

Mon, 01 Jan 0001 00:00:00 +0000

Prometheus metrics

All metrics are exposed at GET /metrics on the admin port (default :9000) in Prometheus text format. No authentication is required to scrape this endpoint.

Traffic (RED)

Metric	Labels	Description
`bouine_requests_total`	`method`, `status`, `cache_result`, `source`, `route`	Total requests processed. This is the primary RED counter.
`bouine_request_duration_seconds`	`method`, `status`, `cache_result`, `source`, `route`	Request latency histogram. Includes native histogram buckets for higher-resolution percentiles. Carries Prometheus exemplars linking high-latency observations to a trace ID when tracing is enabled.
`bouine_response_bytes_total`	`method`, `cache_result`, `source`, `route`	Total bytes written in responses.

cache_result values: HIT, MISS, STALE, REVALIDATED, BYPASS.

TLS

Mon, 01 Jan 0001 00:00:00 +0000

bouine terminates TLS natively for HTTP/1.1. No external TLS proxy is needed.

Minimal TLS config

listen:
 https: ":443"
 admin: ":9000"

tls:
 certs:
 - cert_file: /etc/bouine/tls/cert.pem
 key_file: /etc/bouine/tls/key.pem

Multiple certificates (SNI)

Serve different certificates per hostname:

Clustering

Mon, 01 Jan 0001 00:00:00 +0000

Cluster mode lets multiple bouine pods share cache reads, broadcast invalidations, and reduce origin load.

Choosing a mode

listen:
 cluster: ":8443"

cluster:
 mode: strong # "strong" (default) | "eventual"

Use this decision guide:

Dashboard

Mon, 01 Jan 0001 00:00:00 +0000

The operator dashboard is embedded directly in the admin server — no extra process, no Node toolchain. Open it at:

http://<admin-addr>/dashboard/

Default on localhost: http://localhost:9000/dashboard/

Logging in

The dashboard uses a session cookie derived from the admin bearer token.

Example configurations

Mon, 01 Jan 0001 00:00:00 +0000

Static site / blog

listen:
 http: ":8080"
 admin: ":9000"

storage:
 hot_max_bytes: 64Mo

upstream_pools:
 - name: site
 targets: ["site.default.svc.cluster.local:80"]

routes:
 - match: { path_prefix: /assets/ }
 pool: site
 cache:
 ttl_default: 86400s
 stale_if_error: 604800s
 jitter_percent: 10

 - match: { path_prefix: / }
 pool: site
 cache:
 ttl_default: 300s
 stale_while_revalidate: 60s
 stale_if_error: 86400s
 jitter_percent: 15

Self-served static site (no origin server)

bouine can serve files directly from disk — no separate nginx or Caddy needed. See Static file serving for the full reference.

Kubernetes operations

Mon, 01 Jan 0001 00:00:00 +0000

Scaling

kubectl scale statefulset/bouine -n <namespace> --replicas=3

Gossip auto-discovers peers via the headless Service DNS. New pods join the cluster within 60s.

Rolling update (zero 5xx)

kubectl rollout restart statefulset/bouine -n <namespace>
kubectl rollout status statefulset/bouine -n <namespace> --timeout=180s

StatefulSet rolls one pod at a time (reverse ordinal). Each pod must pass the readiness probe (GET /readyz) before the next is replaced.

Observability guide

Mon, 01 Jan 0001 00:00:00 +0000

This guide walks you through deploying a complete observability stack for bouine using the Grafana LGTM components (Loki, Grafana, Tempo, Mimir/Prometheus) and Grafana Alloy as the unified collection agent.

Architecture

 monitoring namespace
 ┌──────────────────────────────────────────────────┐
 │ Grafana ──queries──▶ Prometheus (metrics) │
 │ Loki (logs) │
 │ Tempo (traces) │
 │ ▲ ▲ ▲ │
 │ Grafana Alloy (single agent) │
 └─────────────────────│────│────│──────────────────┘
 scrape :9000│ │OTLP :4318
 tail pod logs (k8s API) │
 │
 bouine pods

Grafana Alloy replaces three separate agents:

Benchmarks

Mon, 01 Jan 0001 00:00:00 +0000

Disclaimer

Benchmarks are synthetic. They measure isolated behavior in artificial conditions. Production workloads have different allocation patterns, concurrency levels, GC pressure, network conditions, and hardware. The Varnish and NGINX configurations used in these tests could likely be improved — a differently tuned Varnish or NGINX may produce different results. Benchmarking is genuinely hard, and these numbers should be treated as directional indicators, not as definitive performance claims.

Helm chart reference

Mon, 01 Jan 0001 00:00:00 +0000

The Helm chart deploys bouine as a StatefulSet with headless Service for gossip peer discovery. Source: deploy/helm/bouine/.

Install

helm repo add bouine https://charts.bouine.org
helm repo update

helm install bouine bouine/bouine \
 --namespace bouine --create-namespace \
 --set "config.upstream_pools[0].name=app" \
 --set "config.upstream_pools[0].targets[0]=app.default.svc:8080" \
 --set "config.routes[0].pool=app"

To install from a local checkout, replace bouine/bouine with the chart directory deploy/helm/bouine.

Experimental features

Mon, 01 Jan 0001 00:00:00 +0000

Experimental features are opt-in capabilities that bypass some of bouine’s standard processing paths for improved performance. They are gated behind the experimental config section and default to off.

Warning: Experimental features may change or be removed between releases. Test thoroughly before enabling in production.

Production readiness checklist

Mon, 01 Jan 0001 00:00:00 +0000

Before deploying bouine to production, verify each item below. Items are grouped by area. Skip items that don’t apply to your deployment.

TLS and network security

Data-plane TLS configured (if terminating HTTPS at bouine)
Cluster mTLS enabled (cert + key + CA bundle for peer-to-peer)
Admin port not exposed externally (NetworkPolicy or firewall)
Admin token set via Secret or environment variable (not auto-generated)
insecure_skip_verify is not set in any upstream pool TLS config
Hop-by-hop headers stripped (handled automatically by bouine)

Resource sizing

resources.limits.memory set and GOMEMLIMIT auto-computed (Helm chart does this)
hot_max_bytes sized to fit in RAM without GC pressure (default: 75% of GOMEMLIMIT)
Warm tier PVC sized for working set (warmVolume.size)
warm_max_bytes set below PVC capacity to leave headroom
max_object_size configured per route to reject oversized responses
max_response_bytes configured to prevent memory exhaustion from large bodies

Cluster and high availability

replicaCount >= 3 for quorum
podDisruptionBudget.enabled: true with minAvailable >= 2
Topology spread constraints set across zones
hop_limit configured (default 2 is fine for most deployments)
terminationGracePeriodSeconds >= 40 to allow graceful drain
minReadySeconds >= 30 to let the ring converge before traffic

Caching policy

Every route has ttl_default set explicitly
stale_while_revalidate configured for routes that can serve stale
stale_if_error configured for origin-outage resilience
negative_ttl set for routes that return errors (prevents error storms)
jitter_percent > 0 to prevent synchronized revalidation bursts
allow_set_cookie is off unless you explicitly need Set-Cookie caching
Cache key configuration reviewed (query param stripping, header includes)

Upstream and origin

Active health checks enabled per pool
Passive health checks enabled (consecutive_5xx, eject_for)
Upstream connection timeout and response header timeout configured
max_connections set per pool to prevent FD exhaustion
Hedged requests enabled for latency-sensitive routes

Observability

Prometheus scraping enabled (ServiceMonitor or PodMonitor)
Grafana dashboards imported (RED, storage, cluster, ops)
Alerting rules deployed (hit rate, error rate, peer fetch, warm tier)
OpenTelemetry tracing endpoint configured (or disabled explicitly)
Access log sampling rate appropriate (default 1:100 for 200s)
pprof_enabled is off in production (default)

Kubernetes deployment

Helm chart deployed with production values (values-production.yaml as base)
NetworkPolicy.enabled: true to isolate admin and cluster ports
serviceAccount.automount: false (bouine doesn’t need K8s API access)
Probes configured: startup (30 min budget), readiness (/readyz), liveness (/healthz)
Rolling update strategy: maxUnavailable: 1 for sequential pod restarts
Config changes deployed via rolling update (no live config reload)

Operations

Purge and ban workflows documented for on-call
Runbook accessible (see operations docs)
Backup strategy for warm tier (PVC snapshots or rebuild from origin)
Drain procedure tested (/drain endpoint + preStop hook)
Config file stored in version control

Cloudflare CDN propagation

Mon, 01 Jan 0001 00:00:00 +0000

Overview

When bouine sits behind Cloudflare (or any scenario where Cloudflare caches responses delivered through bouine), invalidating a URL in bouine is not enough — the entry may also be cached at the Cloudflare edge.

Service mesh compatibility

Mon, 01 Jan 0001 00:00:00 +0000

bouine works with any service mesh that operates at L4/L7. The main consideration is the double-TLS problem: if the mesh enforces mTLS between sidecars, bouine must either terminate TLS itself or let the sidecar handle it.

Example Post

Mon, 16 Feb 2026 16:31:32 +0100

Use blog posts to communicate product updates and new features in a clear and consistent format.

CLI

Mon, 01 Jan 0001 00:00:00 +0000

Commands

bouine serve --config /etc/bouine/config.yaml
bouine config validate <file>
bouine config schema
bouine completion bash|zsh|fish
bouine purge <url> --token <token>
bouine ban host_regex=example.com path_regex=^/api --token <token>
bouine refresh <url> --token <token>
bouine cluster peers
bouine version

--server defaults to 127.0.0.1:9000. All commands default to port 9000 so --server is optional when running locally.

Admin API

Mon, 01 Jan 0001 00:00:00 +0000

Authentication

All write endpoints require a bearer token. See Authentication for full details on token resolution, environment variables, and config file setup.

Pass the token in requests:

curl -X POST http://127.0.0.1:9000/v1/purge \
 -H "Authorization: Bearer your-secret-token" \
 -H "Content-Type: application/json" \
 -d '{"url":"https://example.com/page"}'

Exempt endpoints (no token required)

These are always accessible without authentication — required for K8s probes and Prometheus scraping:

Response headers

Mon, 01 Jan 0001 00:00:00 +0000

X-Cache

Indicates how the response was served.

Value	Description
`HIT`	Served from cache (fresh)
`MISS`	Fetched from origin and cached
`STALE`	Served from cache (stale, within stale-while-revalidate or stale-if-error window)
`BYPASS`	Cache bypassed (no-store, no-cache, or cache disabled for route)
`REVALIDATED`	Conditional request to origin returned 304, served from cache with updated freshness

curl -sI http://localhost:8080/get | grep x-cache
# X-Cache: HIT

Age

The age of the cached object in seconds, calculated as the time since the Date header of the original response plus any time spent in upstream forward proxies. Updated on every cache hit.

Go SDK

Mon, 01 Jan 0001 00:00:00 +0000

The bouine Go SDK (pkg/bouineapi) provides typed methods for every admin API endpoint. It shares wire types with the Cobra CLI and the admin server, so there is no drift between the SDK and the API.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

General

How is bouine different from Varnish?

bouine is designed for Kubernetes from day one: gossip clustering, Helm chart, Prometheus metrics, and OpenTelemetry tracing are built-in. Varnish requires commercial Varnish Plus or external orchestration for clustering, and uses VCL (an imperative DSL) instead of declarative YAML. See the migration guide for a side-by-side comparison.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Quick reference

Symptom	Severity	Jump to
Pods don’t discover each other	Critical	Cluster discovery
Rolling restart produces 503/502	High	Rolling restart
Purge doesn’t propagate	High	Purge propagation
HIT p99 spikes to 50–100 ms under load	High	GC stop-the-world pauses
`X-Cache` always MISS	Medium	Cache misses
Stale reads on one node	Medium	Stale reads
Low hit rate in eventual mode	Low	Low hit rate
Docker build slow on Apple Silicon	Low	Docker build

Cluster discovery

Pods do not discover each other

Check the headless Service:

Example Guide

Thu, 07 Sep 2023 16:04:48 +0200

Guides lead a user through a specific task they want to accomplish, often with a sequence of steps. Writing a good guide requires thinking about what your users are trying to do.

Example Reference

Thu, 07 Sep 2023 16:13:18 +0200

Reference pages are ideal for outlining how things work in terse and clear terms. Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what your documenting.

Resources

Tue, 27 Feb 2024 09:30:56 +0100

Link to valuable, relevant resources.

404

Mon, 01 Jan 0001 00:00:00 +0000

Privacy Policy

Mon, 01 Jan 0001 00:00:00 +0000