Docker Labels

Define declarative tunnels using Docker container labels.

Written by uartnet

@uartnet

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.

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: ["rstream","run","--docker"]
    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"

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.

Label	Meaning
`rstream.tunnel.<name>.forward`	Upstream target as `port` or `host:port`.
`rstream.tunnel.<name>.publish`	Whether the tunnel is published.
`rstream.tunnel.<name>.protocol`	Tunnel protocol (`http`, `tls`, `dtls`, `quic`).
`rstream.tunnel.<name>.host`	Requested stable domain hostname.
`rstream.tunnel.<name>.upstream-tls`	Enable TLS between engine and upstream.
`rstream.tunnel.<name>.label.<k>`	User-defined label attached to the tunnel.
`rstream.tunnel.<name>.http.version`	Upstream HTTP version (`http/1.1`, `h2c`, `h3`).
`rstream.tunnel.<name>.http.upstreamTLS`	Deprecated HTTP-only alias for upstream TLS.
`rstream.tunnel.<name>.http.auth.token`	Enable token authentication.
`rstream.tunnel.<name>.http.auth.rstream`	Enable rstream auth.
`rstream.tunnel.<name>.http.gate.challenge`	Enable challenge mode.
`rstream.tunnel.<name>.tls.alpns`	Comma-separated custom ALPN values for TLS, DTLS, or QUIC tunnels.

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

YAML Self-Hosted