Repository navigation
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.
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_BINDon127.0.0.1(the default for the binary). With Docker, publish127.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.
The repository ships a production
compose.yml with:
- a non-root user;
- a persistent named volume;
- a
/healthzhealth 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 -fWhat the defaults give you:
- HTTP on
127.0.0.1:6878and RTMP on127.0.0.1:1935on the host. SetOUTPACE_HTTP_HOSTorOUTPACE_RTMP_HOSTto 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.
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.
Pure leecher, in .env:
OUTPACE_ENABLE_INBOUND=0
OUTPACE_ENABLE_SEEDING=0Disk-backed piece cache, in .env:
OUTPACE_CACHE_TYPE=disk
OUTPACE_CACHE_DIR=/var/lib/outpace/cache
OUTPACE_SEED_STORE_BYTES=536870912The 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: 1gMeasure 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.
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.targetsudo systemctl daemon-reload
sudo systemctl enable --now outpace
journalctl -u outpace -fLogs 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.
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'sHostheader. It ignoresX-Forwarded-ProtoandX-Forwarded-Prefix, and it never returnshttps://. 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.
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=1for 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-deploysystemd timer polls the registry once a minute and redeploys when theedgeimage 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.
- Images:
linux/amd64,linux/arm64,linux/arm/v7(releases);edgeislinux/amd64only. - 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=67108864andOUTPACE_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.
-
Back up the data directory (
outpace-datavolume or/var/lib/outpace). It holdsidentity.seedandbroadcasts/. Losing it changes your node identity and the content ids of your broadcasts.cache/doesn't need backing up. -
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 -
Check
/healthz,/networksand 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.
On SIGTERM (docker stop, systemctl stop) outpace:
- stops support sources and live streams, which ends open viewer responses;
- stops broadcasts, allowing cleanup up to 5 seconds;
- drains HTTP connections;
- exits.
Unreleased fix: ending open viewer responses first is in
edgeandmain. 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.
A stream with no viewers, HLS requests or leases is torn down after a 30-second grace period.
Unreleased fix: in
edgeandmain, one stream whose cleanup hangs no longer stops later idle streams from being cleaned up. The log shows[manager] idle cleanup still pendingwhen this happens.
This wiki is generated from docs/wiki/ in the main repository. To fix or improve a page, open a pull request there; the wiki is republished automatically when it merges, and edits made in the wiki web UI are overwritten.
Start
Watching
Publishing and peers
- Broadcasting
- Seeding and Peers
- Engine Camouflage
- NAT and Port Mapping
- Private Peer Mode
- Outbound Proxy
Running it
- Deployment
- Routers and Small Devices
- Migrating from AceStream Engine
- Support Sources and Operations
- Troubleshooting
- Releases and Versions
Success stories