rstream Self-Hosted Deployment

Deployment

Requirements and deployment model for the self-hosted engine.

Written by uartnet

@uartnet

The Community Edition engine runs as one process named rstream-engine-ce. It reads YAML configuration from --config, -c, or RSTREAM_ENGINE_CONFIG, then applies environment overrides with the RSTREAM_ENGINE_ prefix.

CE requires a TLS listener, a static certificate provider, and a JWT authentication backend. It does not issue certificates and does not call the hosted Control plane.

Network Shape

Expose the TLS listener on TCP 443 in production. Agents use it for the rstream control channel, downstream users use it for published HTTPS and TLS tunnels, and API clients use it for /api endpoints. The optional HTTP listener can be exposed on TCP 80 when plain HTTP requests should redirect to HTTPS. Prometheus should stay private, or require a bearer token when exposed outside loopback.

Port	Required	Use
`443/tcp`	Yes	TLS listener for agent control channels, Engine API, and published endpoints.
`80/tcp`	Optional	HTTP redirect listener.
`9090/tcp` or private equivalent	Optional	Prometheus metrics endpoint when enabled.

DNS must point the base engine host and the tunnel wildcard to the server:

edge.example.com       A/AAAA  <engine-public-ip>
*.t.edge.example.com   CNAME   edge.example.com

Agents connect to the base engine host, for example edge.example.com:443. Published stable domains are labels under .t.<engine-host>; a requested label becomes <label>.t.edge.example.com.

TLS Certificate

The static certificate must be valid for every hostname that reaches the TLS listener. For edge.example.com, include at least these SANs:

DNS:edge.example.com
DNS:*.t.edge.example.com

A wildcard for *.edge.example.com is not part of the CE hostname model. CE needs the base engine host and the .t.<engine-host> tunnel wildcard.

The engine loads certs.static.cert_file and certs.static.key_file at startup. It checks file modification times on later TLS handshakes and reloads the pair when either file changes. Certificate sidecars should write new files next to the live files and then rename them into place.

When the engine runs in Docker with bind-mounted certificate files, make the private key readable by the engine process without making it world-readable. A common pattern is to run the engine container with a dedicated host UID/GID and write key.pem with mode 0600 for that same UID.

Minimal Configuration

The minimal CE configuration includes an engine host, TLS listener, static certificate provider, and JWT authentication:

engine:
  host: edge.example.com
  log_level: info
tls:
  enabled: true
  listen_addr: ":443"
certs:
  static:
    enabled: true
    cert_file: /etc/rstream/tls/cert.pem
    key_file: /etc/rstream/tls/key.pem
auth:
  jwt:
    enabled: true
    token_jwt_secret: "<secret>"

In production, keep secrets in environment variables, process-manager secrets, or container secrets instead of YAML:

RSTREAM_ENGINE_AUTH__JWT__TOKEN_JWT_SECRET=...
RSTREAM_ENGINE_CERTS__STATIC__CERT_FILE=/etc/rstream/tls/cert.pem
RSTREAM_ENGINE_CERTS__STATIC__KEY_FILE=/etc/rstream/tls/key.pem

Compose Baseline

The public image is rstream/rstream-engine-ce. A production Compose service should mount configuration and TLS material, keep the JWT secret outside the YAML file, and bind metrics deliberately:

services:
  engine:
    image: rstream/rstream-engine-ce:latest
    command: ["--config", "/etc/rstream/config.yaml"]
    user: "${RSTREAM_RUNTIME_UID}:${RSTREAM_RUNTIME_GID}"
    env_file: [".env"]
    ports:
      - "80:80"
      - "443:443"
      - "127.0.0.1:9090:9090"
    volumes:
      - "./config.yaml:/etc/rstream/config.yaml:ro"
      - "./tls:/etc/rstream/tls:ro"

The matching environment file usually carries deployment-specific bind addresses and secrets:

RSTREAM_ENGINE_AUTH__JWT__TOKEN_JWT_SECRET=...
RSTREAM_ENGINE_CERTS__STATIC__CERT_FILE=/etc/rstream/tls/cert.pem
RSTREAM_ENGINE_CERTS__STATIC__KEY_FILE=/etc/rstream/tls/key.pem
RSTREAM_ENGINE_TLS__LISTEN_ADDR=[::]:443
RSTREAM_ENGINE_HTTP__LISTEN_ADDR=[::]:80
RSTREAM_ENGINE_METRICS__PROMETHEUS__LISTEN_ADDR=127.0.0.1:9090
RSTREAM_RUNTIME_UID=1000
RSTREAM_RUNTIME_GID=1000

If Prometheus binds to a non-loopback address inside the container, configure RSTREAM_ENGINE_METRICS__PROMETHEUS__BEARER_TOKEN and send that bearer token from the scraper.

Agent Context

Agents connect to the base engine host. For edge.example.com, configure the agent engine as edge.example.com:443:

version: 1
defaults:
  context:
    name: self-hosted-ce
contexts:
  - name: self-hosted-ce
    engine: edge.example.com:443
    auth:
      token:
        storage:
          kind: inline
          value: "<jwt-signed-with-engine-secret>"

The token is an HS256 JWT signed with auth.jwt.token_jwt_secret. Give it an expiration and rotate it through the same secret-management path used for other service credentials.

CE Boundary

The public self-hosted deployment documented here is CE. The Compose shape above runs the standalone CE engine with direct JWT agent authentication, static TLS files, Prometheus metrics, and live Engine API state.

Use hosted rstream or contact rstream for a private deployment when the runtime must enforce managed project controls, certificate-backed authentication, browser-based access flows, network access policies, persisted operational history, or automatic certificate management.

Self-Hosted Configuration