centauri-docker-confd

README

centauri-docker-confd

A config server that monitors Docker containers and generates Centauri route configuration, serving it via the network config protocol.

• Monitors Docker containers using containuum
• Generates Centauri route configuration from container labels (compatible with Dotege labels)
• Serves configuration over TCP using the Centauri network config protocol
• Automatically pushes updates when containers start/stop or labels change

Docker Labels

centauri-docker-confd uses the following labels:

• com.chameth.vhost - Comma/space-delimited list of hostnames (required)
• com.chameth.proxy - Optional port number (auto-detected from single exposed port if omitted)
• com.chameth.provider - Optional certificate provider to use (Centauri will use its default if not specified)
• com.chameth.subject - Optional custom certificate subject name to use
• com.chameth.headers.* - Optional response headers (format: Header-Name: value)
• com.chameth.errors.<status> - Optional upstream to generate the response for an error status code (format: host:port or host:port/path)
• com.chameth.proxytag - Optional tag used with the --proxytag option to control which containers are proxied
• com.chameth.splithosts - If set to a true value (true/1), one route is emitted per vhost instead of a single route with alternate names. Cannot be combined with com.chameth.subject.

Configuration

Configuration is done via command-line flags or environment variables:

Flag	Environment Variable	Default	Description
--listen	LISTEN	:8080	TCP address to listen on
--route-extras	ROUTE_EXTRAS	(empty)	Lines to include in every route block (can contain newlines)
--proxytag	PROXYTAG	*	Only process containers with matching com.chameth.proxytag label

The default proxytag value, *, ignores proxytag labels. An explicitly empty value (--proxytag= or PROXYTAG='') selects only containers with a missing or empty com.chameth.proxytag label. Any other value requires an exact label match.

Example Usage

Setting default headers

ROUTE_EXTRAS="header default Strict-Transport-Security max-age=15768000
header delete Server" ./centauri-docker-confd

Configuring Centauri

Configure Centauri to connect to centauri-docker-confd:

CONFIG_SOURCE=network CONFIG_NETWORK_ADDRESS=localhost:8080 centauri

Container labels

services:
  web:
    image: nginx
    labels:
      com.chameth.vhost: "example.com www.example.com"
      com.chameth.proxy: "80"
      com.chameth.subject: "example.com *.example.com"
      com.chameth.headers.csp: "Content-Security-Policy: default-src 'self'"
      com.chameth.errors.502: "error-pages:8080/502.html"

This generates a Centauri config like:

route example.com www.example.com
    upstream web:80
    subject example.com *.example.com
    on_error 502 error-pages:8080/502.html
    header replace Content-Security-Policy default-src 'self'

Provenance

This project was primarily created with Claude Code, but with a strong guiding hand. It's not "vibe coded", but an LLM was still the primary author of most lines of code. I believe it meets the same sort of standards I'd aim for with hand-crafted code, but some slop may slip through. I understand if you prefer not to use LLM-created software, and welcome human-authored alternatives (I just don't personally have the time/motivation to do so).