Docker Labels

In Docker mode, rstream run --docker watches running containers and derives tunnel configuration from container labels. The model is intentionally similar to other label-driven ingress tools: the application containers declare the desired exposure, and a single agent reconciles tunnels.

Only labels with the rstream.tunnel. prefix are considered. Labels are grouped by tunnel name using the <name>.<key> pattern, and each tunnel group must define a forward label.

When a tunnel omits explicit values, the parser defaults publish=true and protocol=http.

For a hands-on Docker Compose workflow that exposes a homelab Grafana dashboard from Docker labels, see Expose a Homelab Grafana Dashboard Without Port Forwarding using rstream.

Compose example

The example below runs the reconciler alongside two services. Each service declares a tunnel through labels.

services:
  rstream:
    image: rstream/rstream:latest
    command: ["run", "--docker", "--watch"]
    restart: unless-stopped
    user: "0:0"
    environment:
      RSTREAM_ENGINE: "<engine>"
      RSTREAM_AUTHENTICATION_TOKEN: "<token>"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
  api:
    image: my-api:latest
    labels:
      rstream.tunnel.api.forward: "8080"
      rstream.tunnel.api.publish: "true"
      rstream.tunnel.api.protocol: "http"
      rstream.tunnel.api.http.auth.token: "true"
  admin:
    image: my-admin:latest
    labels:
      rstream.tunnel.admin.forward: "9000"
      rstream.tunnel.admin.publish: "true"
      rstream.tunnel.admin.protocol: "http"
      rstream.tunnel.admin.http.auth.rstream: "true"

The reconciler needs permission to inspect containers and watch Docker events. On many hosts that means running with access to /var/run/docker.sock, which should be treated as privileged access to the Docker host. For hardened hosts, place a restricted Docker socket proxy in front of the daemon or run the reconciler under the host's normal Docker access controls.

For long-running homelab or server deployments, run the reconciler in the same Compose project as the services it exposes and give it a normal restart policy. If the host already has a working rstream CLI context, mount that context read-only instead of writing a bearer token into the Compose file:

services:
  rstream:
    image: rstream/rstream:latest
    command: ["run", "--docker", "--watch"]
    restart: unless-stopped
    user: "0:0"
    environment:
      RSTREAM_CONFIG: /home/rstream/.rstream/config.yaml
      RSTREAM_CONTEXT: prod
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /home/app/.rstream:/home/rstream/.rstream:ro

After starting or changing labels, verify the reconciled state from the CLI:

rstream tunnel list --filter 'labels.rstream.source=docker'

The Docker watcher logs are intentionally quiet during steady state, so rstream tunnel list is the most direct way to confirm which tunnels exist and which stable domains they use.

Applications that enforce reverse-proxy headers may also need application-level configuration. For example, if an upstream rejects requests after seeing X-Forwarded-For, configure that application to trust the Docker bridge or reverse proxy address before exposing it through a tunnel.

Label schema

The top-level keys under each tunnel name include forward, publish, protocol, type, host, upstream-tls, trusted-ips, geoip, label.<key>, and nested keys under http.* and tls.*. Unknown keys are rejected.

The table below lists the most commonly used label keys.

The host label maps to the tunnel hostname property and is validated as a stable domain inside the current project namespace.