Docker Label-Based Service Discovery#

Overview#

Tinyauth can dynamically discover per-application ACL configuration from running Docker containers by reading labels in the tinyauth.apps.* namespace. This is one of three label-provider modes (docker, kubernetes, none) selected at startup via the LabelProvider config field 1. In auto mode (the default), Tinyauth uses Docker unless KUBERNETES_SERVICE_HOST is set 2.

The Docker socket must be accessible to Tinyauth — in the dev environment, /var/run/docker.sock is mounted directly into the container 3. The LabelProvider field in the AccessControlsService is injected as optional 4, so the service functions normally when no provider is configured.

How Discovery Works#

On each auth request, AccessControlsService.GetAccessControls(domain) first checks static YAML config, then falls back to the label provider. The Docker provider's Lookup method:

1. Lists all running containers via the Docker API 5.
2. Inspects each container for its full label map 6.
3. Decodes labels into a typed model.Apps struct using DecodeLabels, which delegates to the paerser library with the prefix tinyauth.apps 7.
4. For each decoded app, calls a locator callback that tries two match strategies against the incoming domain 8:
   • Exact domain match — compares tinyauth.apps.<name>.config.domain against the request host.
   • Name-prefix match — checks if the request host starts with <app-name>. (e.g., myapp.example.com matches an app key myapp).

Domain match takes priority; the locator returns immediately when a domain match is found. Container inspection errors are non-fatal — Tinyauth logs a warning and continues to the next container 9.

The LabelProvider interface is minimal: a single Lookup(locator func(name string, app *model.App) bool) error method, allowing Docker and Kubernetes providers to be interchangeable.

Label Reference#

All labels follow the pattern tinyauth.apps.<app-name>.<field>. All list values are comma-separated strings 10.

The App struct maps directly to the label hierarchy:

10 11

Key Behaviors and Caveats#

• Static config wins. If a matching app exists in the static YAML Config.Apps map, labels on Docker containers are never consulted for that domain 10.
• No caching. The Docker API is called on every auth request; there is no in-memory cache of container labels.
• Graceful degradation. If Docker is not reachable at startup, NewDockerService returns nil and Tinyauth logs a warning but continues running without label support 12 13.
• IP filtering requires trusted proxies. Per-app ip.* labels only take effect when Auth.TrustedProxies is configured; without it, IP rules are non-operational 10.

Key Files#