DockYARP

Getting started

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

Run the proxy

DockYARP watches the Docker socket and routes to containers based on their labels. Its runtime image is non-root, so it cannot open /var/run/docker.sock directly — it reaches the Docker API through a read-only socket proxy instead:

services:
 dockerproxy:
 image: tecnativa/docker-socket-proxy
 environment:
 CONTAINERS: "1"
 volumes:
 - /var/run/docker.sock:/var/run/docker.sock:ro

 dockyarp:
 image: ghcr.io/gcelet/dockyarp  # or dockyarp:local for a local build
 ports:
 - "80:8080"
 - "443:8443"
 environment:
 Docker__Enabled: "true"
 Docker__DockerEndpoint: "tcp://dockerproxy:2375"
 volumes:
 - certs:/certs
 depends_on: [dockerproxy]

volumes:
 certs:

docker compose up -d

The admin API and dashboard are off by default (AdminApi:Surface: Disabled) — see Examples to turn them on.

Configuration

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

DockYARP is configured two ways: container configuration (per backend, nginx-proxy compatible) and application configuration (the proxy’s own settings). For what these settings do at runtime, see Features.

Container configuration (labels or environment variables)

Every key below can be set as a container label or as an environment variable on the same container. When a key is set both ways, the environment variable wins — environment variables are nginx-proxy’s canonical channel and the label is the fallback. The VIRTUAL_*, LETSENCRYPT_*, CERT_NAME, SSL_POLICY, HTTPS_METHOD, HSTS, NETWORK_ACCESS, SERVER_TOKENS, and EXTERNAL_HTTPS_PORT keys are nginx-proxy compatible; DockYARP’s own keys use the DOCKYARP_ prefix.

Features

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

DockYARP’s runtime behavior, feature by feature. See Configuration for the labels, environment variables, and application settings referenced here.

Discovery

DockYARP watches the Docker daemon and builds its routes from each container’s labels/environment variables, reconciling live as containers start and stop.

Health-aware: a container failing its Docker health check is excluded, so healthy replicas keep serving.
Network selection: on multi-network setups, Docker:PreferredNetwork picks the backend address; Docker:ProxyNetworks restricts selection to a network the proxy shares (reachable), and Docker:HostAddress reaches host-network backends (which have no container IP).
IPv6: the edge listens dual-stack by default (IPv6 and IPv4 clients are served — no toggle needed, unlike nginx-proxy’s opt-in ENABLE_IPV6). Set Docker:PreferIpv6 to forward to a backend’s IPv6 address when it has one (nginx-proxy PREFER_IPV6_NETWORK); a single family is used per backend, so there are no duplicate endpoints.
Filtering: Docker:ContainerFilters scopes discovery with Docker-native filters (for example, only containers labelled dockyarp.enable=true).

Routing & load balancing

Matching: requests route by Host (and an optional path prefix). An exact host beats a wildcard (*.example.com); DOCKYARP_PRIORITY orders same-host routes (higher wins).
Multiport: VIRTUAL_HOST_MULTIPORTS maps host → path → port on a single container.
Path rewrite: VIRTUAL_DEST=/ strips the VIRTUAL_PATH prefix before forwarding.
Regex paths: a ~-prefixed VIRTUAL_PATH (for example ~^/(app1|alt1)/) matches by regular expression; a prefix path beats a regex path, and VIRTUAL_DEST does not apply to a regex path.
Replicas & policy: containers sharing a VIRTUAL_HOST form one cluster; DOCKYARP_LB selects the load-balancing policy — round-robin (default), least-requests, power-of-two-choices, random, or first-alphabetical.
Default host & fallback: Routing:DefaultHost catches unknown hosts; otherwise an unmatched request gets Routing:DefaultResponseStatusCode (404 by default), or an optional redirect via Routing:DefaultResponseLocation.

TLS & ACME

DockYARP terminates TLS and can obtain certificates automatically.

Examples

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

Task-oriented recipes. Each builds on the base stack below and uses real labels/environment variables — see Configuration for every key and Features for the behavior.

Base stack

DockYARP’s runtime image is non-root and cannot open /var/run/docker.sock directly — a read-only Docker socket proxy is required, not optional hardening, for it to reach the Docker API at all. Add the backend services from the recipes below to this docker-compose.yml.

services:
 dockerproxy:
 image: tecnativa/docker-socket-proxy
 environment:
 CONTAINERS: "1"
 volumes:
 - /var/run/docker.sock:/var/run/docker.sock:ro

 dockyarp:
 image: ghcr.io/gcelet/dockyarp  # or dockyarp:local for a local build
 ports:
 - "80:8080"
 - "443:8443"
 environment:
 Docker__Enabled: "true"
 Docker__DockerEndpoint: "tcp://dockerproxy:2375"
 volumes:
 - certs:/certs
 - ./config:/config
 depends_on: [dockerproxy]

volumes:
 certs:

The admin API and dashboard are off by default (AdminApi:Surface: Disabled) — see Dedicated admin host below to turn them on.

Migrating from nginx-proxy

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

DockYARP is built as an nginx-proxy equivalent — most of what an nginx-proxy operator already knows carries over directly. This page covers two migration paths and, separately, the two things operators worry about most: your existing certificates, and being able to roll back if something goes wrong. For the exhaustive feature-by-feature comparison, see the parity matrix in the repository rather than this page.

Either path: only the nginx-proxy stack itself is replaced. Every backend service keeps its existing VIRTUAL_HOST/LETSENCRYPT_HOST-style labels or environment variables unchanged — DockYARP reads the same keys (see Configuration) — so no other stack’s configuration needs to change.

Architecture

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

DockYARP is a .NET application built on YARP (reverse proxy) and Kestrel (web server), using Docker.DotNet for discovery and ACME for certificates.

Flow

Discovery watches the Docker daemon (initial listing + event stream) and produces a normalized view of the running containers.
Mapping turns labelled containers into a routing model (routes + clusters), applying precedence, health awareness, and reachability.
YARP is driven from that model: routes and clusters are updated live as containers change.
TLS/ACME provisions and renews certificates for hosts that declare them; Kestrel selects the right certificate per SNI host.
Security middleware applies HTTPS enforcement, HSTS, headers, access control, and auth.

Modules

Project	Responsibility
`DockYarp.Core`	Domain models, interfaces, stores (leaf project).
`DockYarp.Docker`	Docker discovery + label mapping.
`DockYarp.Tls`	ACME + certificates.
`DockYarp.Security`	HTTPS enforcement, auth, access control.
`DockYarp.AdminApi`	Admin / observability endpoints.
`DockYarp.App`	ASP.NET host: YARP, DI, pipeline.

Design principle

Reverse-proxy behavior is built on YARP extension points (match policies, transforms, dynamic config) and web-server behavior on Kestrel / ASP.NET Core — DockYARP does not reimplement a proxy layer on top of them.

Deployment

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

Docker Compose

DockYARP’s runtime image is non-root and cannot open /var/run/docker.sock directly — it reaches the Docker API through a read-only socket proxy:

services:
 dockerproxy:
 image: tecnativa/docker-socket-proxy
 environment:
 CONTAINERS: "1"
 volumes:
 - /var/run/docker.sock:/var/run/docker.sock:ro
 restart: unless-stopped

 dockyarp:
 image: ghcr.io/gcelet/dockyarp  # or dockyarp:local for a local build
 ports:
 - "80:8080"
 - "443:8443"
 environment:
 Docker__Enabled: "true"
 Docker__DockerEndpoint: "tcp://dockerproxy:2375"
 volumes:
 - dockyarp-certs:/certs
 depends_on: [dockerproxy]
 restart: unless-stopped

 web:
 image: my-app
 labels:
 - "VIRTUAL_HOST=app.example.io"
 - "VIRTUAL_PORT=8080"
 - "LETSENCRYPT_HOST=app.example.io"
 - "LETSENCRYPT_EMAIL=admin@example.io"

volumes:
 dockyarp-certs:

Notes

Only the socket proxy mounts /var/run/docker.sock, and read-only (:ro); DockYARP itself never touches it.
Persist the certificate directory (here /certs) so ACME certificates survive restarts.
Publish host ports 80 and 443 onto the container’s 8080/8443 (its non-root defaults); port 80 also serves the ACME HTTP-01 challenge and HTTP→HTTPS redirects.
Scope discovery on busy hosts with Docker:ContainerFilters (e.g. only containers carrying a given label).
The admin API and dashboard are off by default (AdminApi:Surface: Disabled) — see Examples to turn them on behind a dedicated host.

Reachability, host-network backends, and multi-network setups are covered under Configuration (Docker:ProxyNetworks, Docker:HostAddress).

Contributing

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

DockYARP is developed spec-first with OpenSpec. Every change — feature, fix, or refinement — follows the same loop.

Environment setup

Required for any contribution:

.NET 10 SDK — or skip installing it: build.ps1 / build.sh (Fallout) fetch the SDK pinned by global.json automatically if it’s missing.
Node.js — needed to run the OpenSpec CLI (npx @fission-ai/openspec@latest), the tool every change goes through (propose / apply / archive). This repo has no other Node dependency outside the docs site.
git.
Docker — only required for ./build.ps1 E2E. The unit/integration gate (./build.ps1 Test) needs none.

Using Claude Code

Optional, on top of the above — not a second toolchain. The checked-in .mcp.json (git / microsoft-docs / docker / aspire MCP servers) auto-enables via .claude/settings.json, and .claude/commands/opsx/* + .claude/skills/openspec-* wire the /opsx:* slash commands to the OpenSpec CLI above. None of this is required to contribute — the OpenSpec CLI works standalone from any editor or agent.

Releasing

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

Cutting a release is a small number of manual, GitVersion-informed steps. Once the tag is pushed, everything else — changelog, GitHub Release, image publish — runs automatically.

First release only

DockYARP develops GitFlow-style: pre-1.0, work happens directly on develop, and main does not exist yet. main is created once, at the first release:

git checkout develop
git pull
git checkout -b main
git push -u origin main

From then on, main exists permanently and this step is never repeated.