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. See Capacity and limits.
  • [ ] 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 above max_connections plus about 160 (LimitNOFILE in the example below). Details in Capacity and limits; watch open_files against open_files_limit in /metrics.
  • [ ] 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 ​

ini
[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
sh
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:

sh
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, HLS credentials, and turning [hls] on or off. You can also add or remove [[mounts]] entries: new streams appear without touching the others, and a removed stream disconnects its encoder and listeners. These need a restart: listen, admin_listen, log_filter, a mount's listener_limit, every [limits] value, enabling or disabling [tls], and HLS capacity settings and directory while HLS is on. 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. To make it gentler, drain first: the server refuses new listeners and sources while current ones finish. Use Stop accepting connections on the console's System page, or the API:

sh
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 waits up to shutdown_timeout_ms for connections to finish. Draining is one-way: to accept traffic again, restart. Relays stop reconnecting while draining, and new encoders are refused.

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 and memory, both covered in Capacity and limits.