# lucaslorentz/caddy-docker-proxy architecture

> Architecture diagram of the GitHub repository lucaslorentz/caddy-docker-proxy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lucaslorentz/caddy-docker-proxy
- Repository: https://github.com/lucaslorentz/caddy-docker-proxy

## Overview

Caddy-Docker-Proxy watches Docker resources, turns Caddy-prefixed labels and other supported configuration sources into a Caddyfile, and distributes the resulting Caddy configuration to local or controlled Caddy servers. The README documents label conversion, templates and upstream discovery; sampled code also shows separate container and Swarm service target handling, event-triggered refreshes, and configuration pushes. Some implementation details—especially server selection and optional modes—are represented only at the documented or excerpted level, so uncertain links are omitted.

Main entry points: [`generator/generator.go`](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/generator/generator.go) (Config generator), [`loader.go`](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/loader.go) (Docker loader), [`cmd.go`](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/cmd.go) (CLI startup), [`docker/client.go`](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/docker/client.go) (Docker client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime control"]
  node_command["CLI startup<br/>[cmd.go]"]
  node_options["Runtime options<br/>[options.go]"]
  node_loader["Docker loader<br/>[loader.go]"]
end

subgraph group_discovery["Docker discovery"]
  node_dockerclient["Docker client<br/>[client.go]"]
end

subgraph group_generation["Config generation"]
  node_generator["Config generator<br/>[generator.go]"]
  node_container_targets["Container targets<br/>[containers.go]"]
  node_service_targets["Service targets<br/>[services.go]"]
  node_label_templates["Label templates<br/>[labels.go]"]
  node_label_parser["Label parsing<br/>[fromlabels.go]"]
  node_caddyfile_model["Caddyfile model<br/>[caddyfile.go]"]
  node_caddyfile_merge["Config merging<br/>[merge.go]"]
  node_caddyfile_marshal["Caddyfile marshal<br/>[marshal.go]"]
  node_caddyfile_lexer["Caddyfile lexer<br/>[lexer.go]"]
  node_caddyfile_processor["Caddyfile processing<br/>[processor.go]"]
end

subgraph group_delivery["Caddy delivery"]
  node_push["Config push<br/>[push.go]"]
end

node_operator(("Operator"))
node_docker["Docker Engine"]
node_caddy["Caddy"]

node_operator -->|"starts"| node_command
node_command -->|"configures"| node_options
node_command -->|"starts loader"| node_loader
node_command -->|"starts"| node_caddy
node_loader -->|"creates clients"| node_dockerclient
node_dockerclient -->|"queries and watches"| node_docker
node_loader -->|"creates generator"| node_generator
node_loader -.->|"requests config"| node_generator
node_generator -->|"lists resources"| node_dockerclient
node_generator -->|"gets container IPs"| node_container_targets
node_generator -->|"gets service targets"| node_service_targets
node_generator -->|"renders labels"| node_label_templates
node_label_templates -->|"converts labels"| node_label_parser
node_label_parser -.->|"creates blocks"| node_caddyfile_model
node_generator -.->|"merges configs"| node_caddyfile_merge
node_generator -.->|"serializes result"| node_caddyfile_marshal
node_caddyfile_marshal -->|"tokenizes input"| node_caddyfile_lexer
node_caddyfile_processor -.->|"processes config"| node_caddyfile_model
node_loader -.->|"distributes config"| node_push
node_push -.->|"loads configuration"| node_caddy
node_generator -->|"reads metadata"| node_docker
node_generator -->|"generates Caddyfile"| node_caddyfile_marshal
node_loader -->|"triggers reload"| node_caddy

click node_command "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/cmd.go"
click node_options "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/config/options.go"
click node_loader "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/loader.go"
click node_dockerclient "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/docker/client.go"
click node_generator "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/generator/generator.go"
click node_container_targets "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/generator/containers.go"
click node_service_targets "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/generator/services.go"
click node_label_templates "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/generator/labels.go"
click node_label_parser "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/fromlabels.go"
click node_caddyfile_model "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/caddyfile.go"
click node_caddyfile_merge "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/merge.go"
click node_caddyfile_marshal "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/marshal.go"
click node_caddyfile_lexer "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/lexer.go"
click node_caddyfile_processor "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/processor.go"
click node_push "https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/push.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_command,node_options,node_loader toneBlue
class node_dockerclient toneAmber
class node_generator,node_container_targets,node_service_targets,node_label_templates,node_label_parser,node_caddyfile_model,node_caddyfile_merge,node_caddyfile_marshal,node_caddyfile_lexer,node_caddyfile_processor toneMint
class node_push toneRose
class node_operator,node_docker,node_caddy toneIndigo
```

## Components

### Runtime control

- [CLI startup](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/cmd.go): `cmd.go`
- [Runtime options](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/config/options.go): `config/options.go`
- [Docker loader](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/loader.go): `loader.go`

### Docker discovery

- [Docker client](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/docker/client.go): `docker/client.go`

### Config generation

- [Config generator](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/generator/generator.go): `generator/generator.go`
- [Container targets](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/generator/containers.go): `generator/containers.go`
- [Service targets](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/generator/services.go): `generator/services.go`
- [Label templates](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/generator/labels.go): `generator/labels.go`
- [Label parsing](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/fromlabels.go): `caddyfile/fromlabels.go`
- [Caddyfile model](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/caddyfile.go): `caddyfile/caddyfile.go`
- [Config merging](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/merge.go): `caddyfile/merge.go`
- [Caddyfile marshal](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/marshal.go): `caddyfile/marshal.go`
- [Caddyfile lexer](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/lexer.go): `caddyfile/lexer.go`
- [Caddyfile processing](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/caddyfile/processor.go): `caddyfile/processor.go`

### Caddy delivery

- [Config push](https://github.com/lucaslorentz/caddy-docker-proxy/blob/master/push.go): `push.go`

### Other components

- **Operator**
- **Docker Engine**
- **Caddy**

## Connections

- Operator → CLI startup: starts (evidence: `cmd.go`)
- CLI startup → Runtime options: configures (evidence: `cmd.go`)
- CLI startup → Docker loader: starts loader (evidence: `cmd.go`)
- CLI startup → Caddy: starts (evidence: `cmd.go`)
- Docker loader → Docker client: creates clients (evidence: `loader.go`)
- Docker client → Docker Engine: queries and watches (evidence: `docker/client.go`)
- Docker loader → Config generator: creates generator (evidence: `loader.go`)
- Docker loader → Config generator: requests config
- Config generator → Docker client: lists resources (evidence: `generator/generator.go`)
- Config generator → Container targets: gets container IPs (evidence: `generator/containers.go`)
- Config generator → Service targets: gets service targets (evidence: `generator/services.go`)
- Config generator → Label templates: renders labels (evidence: `generator/labels.go`)
- Label templates → Label parsing: converts labels (evidence: `generator/labels.go`)
- Label parsing → Caddyfile model: creates blocks
- Config generator → Config merging: merges configs
- Config generator → Caddyfile marshal: serializes result
- Caddyfile marshal → Caddyfile lexer: tokenizes input (evidence: `caddyfile/marshal.go`)
- Caddyfile processing → Caddyfile model: processes config
- Docker loader → Config push: distributes config
- Config push → Caddy: loads configuration
- Config generator → Docker Engine: reads metadata (evidence: `README.md`)
- Config generator → Caddyfile marshal: generates Caddyfile (evidence: `README.md`)
- Docker loader → Caddy: triggers reload (evidence: `README.md`)
