Production checklist

A short list of things to do before you put real listeners on your station, followed by how to run, reload and restart it safely.

Before you go live

• [ ] Validate the config: quikcast --config quikcast.toml --check
• [ ] Use HTTPS, either built in or via a proxy.
• [ ] Keep the admin address private. admin_listen must be loopback. Never forward /api, /internal, /health or /metrics.
• [ ] Use unique, random passwords for each mount, HLS, the management token and the console. Keep them in files readable only by the service user (chmod 600).
• [ ] Set listener limits that match your server's bandwidth. 1,000 listeners at 128 kbit/s is about 128 Mbit/s outbound.
• [ ] Set up monitoring: scrape /metrics and alert when active_sources is 0. See Monitoring.
• [ ] Tell Quikcast about your proxy with trusted_proxies if you use one, so rules see real addresses.
• [ ] Raise the file descriptor limit (ulimit -n or LimitNOFILE) above max_connections. Each listener is a connection.
• [ ] Test a reload (kill -HUP) and a restart on a quiet day.
• [ ] Back up quikcast.toml and your secrets/ folder. There is no other state to save.

Run it as a service

systemd

[Unit]
Description=Quikcast streaming server
After=network-online.target
Wants=network-online.target

[Service]
User=quikcast
Group=quikcast
ExecStart=/usr/local/bin/quikcast --config /etc/quikcast/quikcast.toml
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
LimitNOFILE=65536
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

sudo useradd --system --no-create-home --shell /usr/sbin/nologin quikcast
sudo systemctl daemon-reload
sudo systemctl enable --now quikcast

Logs go to the journal automatically: journalctl -u quikcast -f.

Docker

The repository's docker-compose.yml is a good starting point. In your own setup remember:

• listen = "0.0.0.0:8000" inside the container, and publish only port 8000.
• Mount your config at /etc/quikcast/quikcast.toml and secrets at /etc/quikcast/secrets/, read-only.
• The container runs as a non-root user, so secret files must be readable by it.
• Health checks run inside the container against 127.0.0.1:9090.
• Reload with docker compose kill -s HUP quikcast.

Change settings without stopping

Edit the config (or a secret, certificate or list file), validate it, and send a reload:

quikcast --config /etc/quikcast/quikcast.toml --check && kill -HUP "$(pidof quikcast)"

(With systemd: sudo systemctl reload quikcast.)

A reload is all or nothing. If anything is wrong the running configuration is kept and the reason is logged. Connected encoders and listeners are not interrupted.

These apply on reload: passwords, certificates, [trusted_proxies], [access] and its list files, backups (fallback), signed-link keys, relays, [sources], the console and HLS credentials. These need a restart: listen, admin_listen, log_filter, adding or removing mounts, every [limits] value, enabling or disabling [tls], and HLS capacity settings. See the full table.

The signal returns immediately and does not say whether it worked. Check the logs, or compare config_generation and config_reload_failures_total in the metrics.

Rotating a password

Change the file, then reload. Connected encoders stay connected; the next connection needs the new password.

Restarting without dropping listeners

A restart disconnects everyone, and listeners must reconnect. To make it gentler, drain first. Draining refuses new work while letting current listeners and encoders finish:

curl -X POST -H "Authorization: Bearer $(cat secrets/management-token)" \
  http://127.0.0.1:9090/api/server/drain

After draining, /health/ready returns 503, so a load balancer stops sending new listeners. When you are ready, stop the process with SIGTERM (or Ctrl+C). Quikcast closes listeners and waits up to shutdown_timeout_ms for connections to finish.

Draining is one-way: to accept traffic again, restart.

What a restart resets

All runtime state is in memory: connected sources and listeners, statistics, listener history, relay start/stop choices and everything in HLS. Encoders and players reconnect on their own, and your HLS producer must publish again.

Upgrading

1. Download the new release and read its notes.
2. Run the new binary's --check against your existing config.
3. Replace the binary and restart (drain first if you want a gentle stop).

Sizing

Audio is not re-encoded, so CPU use is low. What grows is outbound bandwidth (listeners × bitrate) and memory. Memory is bounded by retained_audio_budget, which Quikcast checks at startup against your listener limits. See Capacity and limits for the details.