Install
The install script sets up the single program, quikcast. The console and the country database are built in, so there is nothing else to install.
Requirements
Quikcast is one program with no database and no other runtime.
Supported systems. Linux on x86_64 or arm64 with glibc 2.35 or newer.
Other distributions with glibc 2.35 or newer also work. Alpine (musl) is not supported. Running it as a service needs systemd.
Minimum resources.
- 1 vCPU and 512 MB of RAM. Audio is passed through, not re-encoded. One mount with 1,000 listeners used about a third of a core and 65 MB in testing.
- 50 MB of disk. The program is about 15 MB.
- Bandwidth is the real limit. Each listener downloads the stream's bitrate, so 1,000 listeners on a 128 kbps stream need about 128 Mbps of upload.
For larger audiences see Capacity and limits.
Install script (recommended)
One command installs the quikcast program and the qc helper into /usr/local/bin, so you can run quikcast from anywhere:
curl -fsSL https://rpstatic.streamafrica.net/quikcast/install.sh | sh
quikcast --versionThe script checks that your system is supported, verifies the download against its published SHA-256 checksum, and refuses to install if it does not match. Run it again at any time to update.
To also run Quikcast as a background service that starts on boot, add --service:
curl -fsSL https://rpstatic.streamafrica.net/quikcast/install.sh | sh -s -- --serviceOn a first install from a terminal, the script offers to run qc setup, a guided setup that asks who should reach your stream and sets up HTTPS if you want it. Scripts and CI never get a prompt.
That creates a quikcast system user, a starter configuration in /etc/quikcast/quikcast.toml with the operator console already on, generated passwords for encoders and for the console in /etc/quikcast/secrets/, and a systemd service, then starts it. Show the passwords with qc password. An existing configuration is never overwritten. The server listens on 127.0.0.1:8000 until you change listen.
| Option | What it does |
|---|---|
--version X.Y.Z | Install a specific version instead of the latest. |
--service | Set up the systemd service and starter configuration (needs systemd and root). |
--listen ADDR | Public address for a new configuration, such as 0.0.0.0:8000. The default only accepts connections from the machine itself. |
--domain NAME | Serve HTTPS on port 443 with a free Let's Encrypt certificate. Repeat it, or separate names with commas, for one certificate covering several names. Needs certbot, DNS pointing at the server and port 80 free. Accepts the Let's Encrypt terms, renews automatically and reloads Quikcast. |
--email ADDR | Contact address for Let's Encrypt, with --domain. |
--tls-cert FILE, --tls-key FILE | Serve HTTPS on port 443 with your own certificate and key. |
--prefix DIR | Install into DIR instead of /usr/local/bin. |
--restart | Restart the service after installing. |
--listen, --domain and --tls-* are applied with qc listen and qc tls (below). The previous configuration is kept as quikcast.toml.bak, and a change that fails the configuration check is not applied. The service may bind ports below 1024, so 443 works without root.
Manage Quikcast with qc
qc is installed next to quikcast. Setup commands:
| Command | What it does |
|---|---|
qc setup | Guided setup: service, public address and HTTPS. Safe to run again. |
qc listen [ADDR] | Show or change the public address, such as 0.0.0.0:8000. |
qc tls --domain NAME [--domain NAME2] | HTTPS on port 443 with one free Let's Encrypt certificate covering every name (needs certbot). Renewals are copied in and reloaded automatically. |
qc tls --cert FILE --key FILE | HTTPS with your own certificate. |
qc tls off | Serve plain HTTP again. |
qc menu | A guided menu for everything below. |
qc info | One-screen summary of this server. |
qc management [on | off] | Set up the management API for panels and scripts. Asks who may connect (this machine, specific IPs, or anyone), whether to use HTTPS, and generates its own token. |
qc console [on | off] | Show, enable or disable the web dashboard. on --status-page also publishes a small public status page. |
qc password [reset encoder|console|all] | Show or replace the encoder and console passwords. |
qc config | Edit the configuration; it is checked before it is saved. |
qc doctor | Check the install and explain what is wrong, such as an address that only accepts local connections or a blocked port. |
Quikcast serves a single certificate, so several domains share one certificate that lists all of them. Every name must point at this server, and port 80 must be free while the certificate is requested. qc tls also keeps the console's cookie and public address in step with HTTPS. Changing the address or turning HTTPS on or off needs a restart: add --restart or run qc restart. Every change keeps the previous file as quikcast.toml.bak.
Updating and running:
| Command | What it does |
|---|---|
qc update | Install the latest version. Your running station keeps playing until you restart it. |
qc update --restart | Update and restart the service. |
qc rollback | Go back to the previous version. |
qc version | Show the installed and the latest version. |
qc check [CONFIG] | Validate a configuration (default /etc/quikcast/quikcast.toml). |
qc status, start, stop, restart | Control the service. |
qc reload | Apply configuration changes without dropping listeners. |
qc logs [-f] | Show the service log. |
qc uninstall [--purge] | Remove Quikcast. --purge also deletes /etc/quikcast. |
An update replaces the program file but does not restart a running server, because a restart disconnects listeners. Apply it with qc restart when you are ready, or drain first.
Check your install
Write a small config and let Quikcast validate it without starting:
quikcast --config quikcast.toml --checkIt prints configuration ok when all is well. The quickstart walks through the file.