Skip to content
ella-toPublic

About

a dynamic reverse http proxy

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

49 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

██████╗░░█████╗░██╗░░██╗███████╗██████╗░
██╔══██╗██╔══██╗██║░██╔╝██╔════╝██╔══██╗
██████╦╝███████║█████═╝░█████╗░░██████╔╝
██╔══██╗██╔══██║██╔═██╗░██╔══╝░░██╔══██╗
██████╦╝██║░░██║██║░╚██╗███████╗██║░░██║
╚═════╝░╚═╝░░╚═╝╚═╝░░╚═╝╚══════╝╚═╝░░╚═╝

Go Reference Go Report Card License: MIT

Introduction

Baker is a dynamic HTTP reverse proxy with a focus on extensibility and flexibility. It is designed to adapt to a variety of orchestration engines and provides dynamic configuration capabilities, eliminating the need to restart the reverse proxy when changing configurations.

Features

Feature Description
🐳 Docker Integration Native Docker driver for real-time container event listening
🔌 Pluggable Drivers Exposed driver interface for easy integration with other orchestration engines
⚡ Dynamic Config Hot-reload configuration without restarts
🌳 Fast Routing Custom trie data structure for high-performance path pattern matching
📚 Library Mode Use as a library—implements the standard http.Handler interface
🔧 Extensible Exposed interfaces for most components
🔀 Middleware Modify incoming and outgoing traffic with built-in or custom middleware
⚖️ Load Balancing Built-in load balancing across service instances
🔒 Auto SSL Automatic HTTPS: Let's Encrypt for public domains + local CA certs for *.localhost
🚦 Rate Limiting Configurable rate limiter per domain and path
📊 Observability OpenTelemetry traces, metrics and logs exported over OTLP
📋 Static Config Support for services without dynamic configuration endpoints
🔄 WebSocket Full WebSocket proxy support

Quick Start

1. Deploy Baker

Create a docker-compose.yml for Baker:

services:
  baker:
    image: ellato/baker:latest
    environment:
      - BAKER_ACME=NO              # Enable/disable ACME (Let's Encrypt)
      - BAKER_ACME_PATH=/acme/cert # Certificate storage path
      - BAKER_LOG_LEVEL=DEBUG      # Log level: DEBUG, INFO, WARN, ERROR
      - BAKER_BUFFER_SIZE=100      # Event buffer size
      - BAKER_PING_DURATION=2s     # Health check interval
      - BAKER_ACCESS_LOG=/var/log/baker/access.log # stdout (default), stderr, off, or a file
      # OpenTelemetry (service.name/version are set by baker at build time)
      - OTEL_DEPLOYMENT_ENVIRONMENT=dev
      - OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317
      - OTEL_EXPORTER_OTLP_INSECURE=true
      - OTEL_TRACES_SAMPLER=parentbased_traceidratio
      - OTEL_TRACES_SAMPLER_ARG=1.0
      - OTEL_METRIC_EXPORT_INTERVAL=15s
      - ELLA_OTEL_DISABLED=false   # Set to true if no OTLP collector is running
      - ELLA_OTEL_LOGS_ENABLED=true
      - ELLA_OTEL_LOGS_STDOUT=true
      - ELLA_OTEL_LOGS_LEVEL=info
    ports:
      - "80:80"
      - "443:443"
    networks:
      - baker
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./acme/cert:/acme/cert
      - ./logs:/var/log/baker

networks:
  baker:
    name: baker
    driver: bridge

2. Configure Your Service

Add Baker labels to your service's docker-compose.yml:

services:
  my-service:
    image: my-service:latest
    labels:
      - "baker.enable=true"
      - "baker.network=baker"
      - "baker.service.port=8000"
      - "baker.service.ping=/config"
      # Optional: Static configuration (for non-dynamic services)
      - "baker.service.static.domain=api.example.com"
      - "baker.service.static.path=/*"
      - "baker.service.static.headers.host=api.example.com"
    networks:
      - baker

networks:
  baker:
    name: baker
    external: true

Note: Ensure both Baker and your service share the same Docker network.

Configuration

Environment Variables

Variable Default Description
BAKER_ACME NO Enable HTTPS (YES): Let's Encrypt for public domains and local certificates for *.localhost
BAKER_ACME_PATH /acme/cert Directory for SSL certificates
BAKER_LOG_LEVEL INFO Logging level
BAKER_BUFFER_SIZE 100 Docker event buffer size
BAKER_PING_DURATION 2s Service health check interval
BAKER_ACCESS_LOG stdout Access log destination: stdout, stderr, off, or a file path (appended to, reopened on SIGHUP for logrotate)

OpenTelemetry Environment Variables

Baker initialises the ella.to/otel SDK at startup and always overrides service.name (baker) and service.version (injected at build time), so setting OTEL_SERVICE_NAME or OTEL_SERVICE_VERSION has no effect.

Telemetry is enabled by default and exported to localhost:4317. If no OTLP collector is reachable there, baker will repeatedly log errors such as traces export: ... dial tcp [::1]:4317: connect: connection refused. Either point OTEL_EXPORTER_OTLP_ENDPOINT at your collector (e.g. otel-collector:4317 on the same Docker network) or disable telemetry with ELLA_OTEL_DISABLED=true. Boolean values accept true/false/1/0, not YES/NO.

Variable Default Description
OTEL_DEPLOYMENT_ENVIRONMENT dev Sets deployment.environment resource attribute
OTEL_EXPORTER_OTLP_ENDPOINT localhost:4317 OTLP gRPC collector endpoint (host:port or http(s)://…)
OTEL_EXPORTER_OTLP_INSECURE true Disable TLS for plain :4317
OTEL_EXPORTER_OTLP_HEADERS (none) Extra headers sent to the collector (key=value,key=value)
OTEL_TRACES_SAMPLER parentbased_traceidratio Head sampler (always_on, always_off, parentbased_traceidratio, …)
OTEL_TRACES_SAMPLER_ARG 1.0 Sampling ratio when sampler is *_traceidratio
OTEL_METRIC_EXPORT_INTERVAL 15s Metric export interval (duration string)
OTEL_RESOURCE_ATTRIBUTES (none) Extra resource attributes (region=fra1,role=edge)
ELLA_OTEL_DISABLED false Install no-op providers (disables all telemetry)
ELLA_OTEL_LOGS_ENABLED true Export logs via OTLP
ELLA_OTEL_LOGS_STDOUT true Also write JSON logs to stdout
ELLA_OTEL_LOGS_LEVEL info Minimum log level (debug/info/warn/error)

Service Labels

Label Required Description
baker.enable Yes Enable Baker for this container
baker.network Yes Docker network name
baker.service.port Yes Service port to proxy to
baker.service.ping Yes Health check / config endpoint
baker.service.static.domain No Static domain (bypasses dynamic config)
baker.service.static.path No Static path pattern
baker.service.static.headers.* No Custom headers to add

Dynamic Configuration Endpoint

Your service should expose a REST endpoint (specified by baker.service.ping) that returns routing configuration:

[
  {
    "domain": "example.com",
    "path": "/api/v1",
    "ready": true
  },
  {
    "domain": "example.com",
    "path": "/api/v2",
    "ready": false
  },
  {
    "domain": "app.example.com",
    "path": "/app/*",
    "ready": true,
    "rules": [
      {
        "type": "ReplacePath",
        "args": {
          "search": "/app",
          "replace": "",
          "times": 1
        }
      }
    ]
  }
]
Field Type Description
domain string Domain to match
path string Path pattern (supports * wildcard)
ready boolean Whether the route is active
rules array Optional middleware rules

Logging

Access log

Every request reaching baker (HTTP and HTTPS, matched or not, including WebSockets) is written as one line in nginx's combined format, followed by extra key=value fields:

203.0.113.7 - - [18/Nov/2026:13:25:32 +0000] "POST /users/42?x=1 HTTP/1.1" 201 10 "https://ref.example.com/" "curl/8.4.0" "-" "api.example.com" req_bytes=17 rt=0.012 upstream=172.18.0.5:8000 container="my-api" route="api.example.com/*" scheme=https tls=TLSv1.3 trace_id=4bf92f3577b34da6a3ce929d0e0e4736
Field Meaning
203.0.113.7 Client IP ($remote_addr)
- Basic-auth user, if any ($remote_user)
[...] Time the request arrived (rt is how long it took)
"POST /users/42?x=1 HTTP/1.1" Raw request line, query string included
201 10 Status and response body bytes sent
"referer" "user-agent" "x-forwarded-for" As nginx's default main format
"api.example.com" Host requested
req_bytes Request body bytes received
rt Total time in seconds (ms precision)
upstream / container / route Backend address, container name and matched route (- on 404)
scheme / tls http or https, and the TLS version
trace_id OpenTelemetry trace id (also returned as the X-Trace-Id header)

Status 499 means the client went away before the backend answered. For a WebSocket the line is written when the connection closes, with status 101 and the bytes exchanged in each direction over the whole connection. Quotes, backslashes and control characters in client-supplied values are escaped as \xHH, so a request cannot forge log lines.

Server log

The server log (JSON when OpenTelemetry stdout logs are enabled) records only changes to the routing table, so it reads as a history of what was routed where:

  • container registered / container changed, re-registering / container removed — with container name, short id and internal IP:port
  • route added / route removed / route rules changed — domain, path, container and replica count
  • container config ping failed (first failure only), container is not responding, removing its routes, container config endpoint is responding again

Pings that return the same config as before log nothing (repeated failures are logged at DEBUG only).

HTTPS for Localhost Domains

When BAKER_ACME=YES, Baker supports both public and local development HTTPS:

  • Public domains (e.g. api.example.com) use Let's Encrypt certificates.
  • Localhost domains (e.g. app.localhost, api.localhost) use certificates generated locally by Baker.

Localhost certificate files are written under:

  • <BAKER_ACME_PATH>/localhost/ca.crt
  • <BAKER_ACME_PATH>/localhost/*.crt
  • <BAKER_ACME_PATH>/localhost/*.key

To trust localhost certificates on macOS (system-wide, requires admin):

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain <BAKER_ACME_PATH>/localhost/ca.crt

To trust without sudo for only the current user (login keychain):

security add-trusted-cert -d -r trustRoot -k ~/Library/Keychains/login.keychain-db <BAKER_ACME_PATH>/localhost/ca.crt

After trusting the CA, domains that are already registered in Baker (for example via labels or dynamic config) can be served over HTTPS as https://<name>.localhost.

Middleware

Baker includes several built-in middleware for request/response modification:

ReplacePath

Replaces or removes parts of the request path before forwarding to the backend service.

{
  "type": "ReplacePath",
  "args": {
    "search": "/api/v1",
    "replace": "",
    "times": 1
  }
}
Argument Type Description
search string Pattern to search for
replace string Replacement string
times integer Number of replacements (-1 for all)

Example: Request to /api/v1/users → Backend receives /users


AppendPath

Adds prefixes and/or suffixes to the request path.

{
  "type": "AppendPath",
  "args": {
    "begin": "/v2",
    "end": ".json"
  }
}
Argument Type Description
begin string Prefix to add
end string Suffix to add

Example: Request to /users → Backend receives /v2/users.json


RateLimiter

Applies rate limiting per client IP address. Supports two algorithms:

  • Sliding Window (window): Smooths out bursts by considering requests from the previous window. Default algorithm.
  • Token Bucket (bucket): Allows controlled bursts up to the bucket capacity, with tokens refilling over time.

Sliding Window (default):

{
  "type": "RateLimiter",
  "args": {
    "request_limit": 100,
    "window_duration": "60s"
  }
}

Token Bucket:

{
  "type": "RateLimiter",
  "args": {
    "algo": "bucket",
    "request_limit": 100,
    "window_duration": "60s"
  }
}
Argument Type Description
algo string Algorithm: window (default) or bucket
request_limit integer Maximum requests per window / bucket capacity
window_duration string Time window or refill duration (e.g., 60s, 1m, 1h)

When the limit is exceeded, clients receive a 429 Too Many Requests response.

License

Baker is licensed under the MIT LICENSE.

About

a dynamic reverse http proxy

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages