Skip to content

Deployment

github-actions[bot] edited this page Nov 12, 2026 · 18 revisions

Deployment

This page covers running Outpace permanently: with Docker Compose, as a systemd service, behind a reverse proxy and in an LXC guest. It also covers upgrades, rollback and shutdown.

Exposing the API safely

The HTTP API has no authentication, and some of its routes change state:

  • stopping streams;
  • creating and deleting broadcasts;
  • attaching pull sources;
  • starting and stopping support sources.

So:

  • Keep OUTPACE_BIND on 127.0.0.1 (the default for the binary). With Docker, publish 127.0.0.1:6878:6878.
  • To serve players on your LAN, either bind to the LAN address and firewall the port to trusted clients, or put an authenticating reverse proxy in front.
  • Treat RTMP (1935) and SRT the same way. Anyone who can reach RTMP can publish to any broadcast name.
  • Only the peer port (TCP 8621) is meant to be public.

Docker Compose

The repository ships a production compose.yml with:

  • a non-root user;
  • a persistent named volume;
  • a /healthz health check;
  • log rotation (3 × 10 MB);
  • a 30-second stop grace period;
  • loopback-only HTTP and RTMP.
cp .env.example .env
# set OUTPACE_IMAGE=ghcr.io/jamezrin/outpace:0.9.0 (pin a release)
docker compose config        # check the result
docker compose up -d --wait
curl --fail http://127.0.0.1:6878/healthz
docker compose logs -f

What the defaults give you:

  • HTTP on 127.0.0.1:6878 and RTMP on 127.0.0.1:1935 on the host. Set OUTPACE_HTTP_HOST or OUTPACE_RTMP_HOST to publish them elsewhere.
  • The peer port published on 0.0.0.0:8621/tcp. Keep this mapping fixed at 8621:8621.
  • A full participant (inbound and seeding on), port mapping off, memory cache, compatibility API off.

After changing .env, run docker compose up -d --wait. docker compose restart doesn't apply environment changes.

Passing other settings

compose.yml only forwards a fixed list of variables into the container (listed in Configuration). Anything else in .env is silently ignored. Put other settings in a compose.override.yml next to it:

services:
  outpace:
    environment:
      OUTPACE_ACE_COMPAT: "1"
      OUTPACE_PREBUFFER_MS: "10000"
      OUTPACE_HLS_STARTUP_SEGMENTS: "3"
      OUTPACE_MAX_SESSIONS: "8"
      OUTPACE_BROADCAST_OPTIONS: '${OUTPACE_BROADCAST_OPTIONS-{}}'

The last line forwards a value from .env; the others set it directly. Then run docker compose up -d --force-recreate --wait.

Common variations

Pure leecher, in .env:

OUTPACE_ENABLE_INBOUND=0
OUTPACE_ENABLE_SEEDING=0

Disk-backed piece cache, in .env:

OUTPACE_CACHE_TYPE=disk
OUTPACE_CACHE_DIR=/var/lib/outpace/cache
OUTPACE_SEED_STORE_BYTES=536870912

The cache may sit inside the data volume as shown, but it must not be the data directory itself.

Custom DNS resolvers, CPU and memory limits, in compose.override.yml:

services:
  outpace:
    dns: [1.1.1.1, 9.9.9.9]
    deploy:
      resources:
        limits:
          cpus: "2"
          memory: 1g

Measure your real workload before you set a memory limit. Each live stream needs memory for its startup buffer (up to 128 MiB), seeding store, HLS window and timeshift budget, if enabled.

systemd

Create a user and an environment file:

sudo useradd --system --home-dir /var/lib/outpace --shell /usr/sbin/nologin outpace
sudo install -d -m 0750 /etc/outpace
sudo tee /etc/outpace/outpace.env >/dev/null <<'EOF'
OUTPACE_BIND=127.0.0.1:6878
OUTPACE_RTMP_BIND=127.0.0.1:1935
OUTPACE_DATA_DIR=/var/lib/outpace
EOF
sudo chmod 0640 /etc/outpace/outpace.env

/etc/systemd/system/outpace.service:

[Unit]
Description=outpace streaming engine
Wants=network-online.target
After=network-online.target

[Service]
User=outpace
Group=outpace
EnvironmentFile=/etc/outpace/outpace.env
ExecStart=/usr/local/bin/outpace serve
Restart=on-failure
RestartSec=5
StateDirectory=outpace
StateDirectoryMode=0700
TimeoutStopSec=30
LimitNOFILE=65536
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now outpace
journalctl -u outpace -f

Logs go to standard error. Each line starts with a UTC time of day (HH:MM:SS.mmm), and the journal adds the date. Open TCP 8621 in your firewall if you run as a full participant.

Behind a reverse proxy

A proxy is the usual way to add TLS and authentication. Things to get right:

  • Don't buffer streams. Turn off response buffering, and allow long reads: a live TS response never ends.
  • Native routes use root-relative URLs (/streams/...). Serve Outpace at the root of its own host name, not under a sub-path.
  • The compatibility API builds absolute http://<Host>/... URLs from the request's Host header. It ignores X-Forwarded-Proto and X-Forwarded-Prefix, and it never returns https://. Clients that follow returned URLs through a TLS-only proxy will fail unless the proxy also serves plain HTTP on that host, or rewrites the response bodies.

An nginx example with basic authentication:

server {
    listen 443 ssl;
    server_name outpace.example.com;
    # ssl_certificate ...;

    auth_basic "outpace";
    auth_basic_user_file /etc/nginx/outpace.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:6878;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_buffering off;
        proxy_request_buffering off;   # for broadcast PUT uploads
        proxy_read_timeout 1h;
        client_max_body_size 0;        # broadcast PUT bodies are unbounded
    }
}

Most players can't send basic-auth credentials in a URL. For players, a LAN-only firewall rule is often simpler than proxy authentication.

LXC guest behind Cloudflare WARP

There is a tested setup for running the image in an unprivileged Proxmox LXC guest that follows edge automatically and sits behind Cloudflare WARP. It is in docs/deployment-lxc-warp.md, with scripts in tools/deploy/lxc/. In short:

  • The guest needs nesting=1,keyctl=1 for Docker and the TUN device for WARP. Give it a static LAN address that no other guest uses, including stopped ones.
  • The provided Compose file uses host networking, so WARP applies to the daemon directly.
  • An outpace-deploy systemd timer polls the registry once a minute and redeploys when the edge image changes.

The inbound-peer caveat: with WARP in Warp mode, a correctly forwarded peer port never completes a handshake. WARP's firewall drops inbound connections from public addresses, and its routing sends replies into the tunnel. The warp-inbound-fix helper service opens exactly one TCP port through WARP by:

  • marking the inbound packets;
  • turning on net.ipv4.tcp_fwmark_accept;
  • reusing WARP's own bypass mark.

It depends on undocumented WARP internals, so recheck it after WARP upgrades. Without it, run the node as download-only, or run it outside WARP.

To compare two engines behind one router, give each its own external peer port and set OUTPACE_PEER_LISTEN to match.

Linux portability

  • Images: linux/amd64, linux/arm64, linux/arm/v7 (releases); edge is linux/amd64 only.
  • ARMv7 means hard-float ARMv7 such as Raspberry Pi 2/3. ARMv6 and soft-float aren't supported. Expect fewer simultaneous streams; start with OUTPACE_CACHE_TYPE=disk, OUTPACE_SEED_STORE_BYTES=67108864 and OUTPACE_SESSION_BUFFER=64.
  • On 32-bit systems each in-memory pool is capped at about 512 MiB. Disk caches can be larger.
  • ARM64 kernels with 16 KiB pages haven't been verified on real hardware.
  • No UDP port needs publishing on any platform.

Upgrades and rollback

  1. Back up the data directory (outpace-data volume or /var/lib/outpace). It holds identity.seed and broadcasts/. Losing it changes your node identity and the content ids of your broadcasts. cache/ doesn't need backing up.

  2. Change the pinned version and restart:

    # Compose: edit OUTPACE_IMAGE in .env, then
    docker compose pull
    docker compose up -d --wait
    curl --fail http://127.0.0.1:6878/healthz
  3. Check /healthz, /networks and the logs before you delete the old image.

Rollback is the same with the older tag. If you run broadcasts, older binaries can reuse piece numbers after a rollback, and so can restoring an older snapshot of the data volume. To roll back safely: stop the broadcast, delete it (DELETE /broadcast/<name>), roll back, then create a fresh broadcast.

docker compose down keeps the volume. docker compose down --volumes deletes your identity and broadcasts for good.

Graceful shutdown

On SIGTERM (docker stop, systemctl stop) outpace:

  1. stops support sources and live streams, which ends open viewer responses;
  2. stops broadcasts, allowing cleanup up to 5 seconds;
  3. drains HTTP connections;
  4. exits.

Unreleased fix: ending open viewer responses first is in edge and main. On v0.9.0, a connected viewer keeps the process alive until it disconnects, or until the stop timeout kills it (30 seconds in the provided Compose file).

A stuck filesystem operation can't be cancelled. In that case cleanup gives up after its grace period and logs it. Already-connected RTMP publisher sockets can stay open until the process exits.

Idle streams

A stream with no viewers, HLS requests or leases is torn down after a 30-second grace period.

Unreleased fix: in edge and main, one stream whose cleanup hangs no longer stops later idle streams from being cleaned up. The log shows [manager] idle cleanup still pending when this happens.

Related pages

Clone this wiki locally