Deploy on Dokploy
Dokploy is a self-hosted platform that runs Docker apps behind Traefik with automatic HTTPS. This guide deploys Quikcast on it with a domain, your own config and secrets, and a health check, in about 15 minutes (mostly the first build). You need a server with Dokploy, a domain pointing at it, and the Quikcast repository or image.
How the pieces fit
Traefik terminates HTTPS and forwards plain HTTP to port 8000. The private admin port (9090) stays inside the container: the image's health check uses it, and nothing outside should.
1. Create the application
- In Dokploy, open a Project and choose Create Service → Application.
- Under Provider pick how Dokploy gets the code:
- GitHub / Git: connect the Quikcast repository, pick the branch, and set Build Type to Dockerfile with path
./Dockerfile. The first build compiles Rust and takes several minutes; later builds reuse the dependency cache. - Docker: if you build the image yourself (
docker build -t ghcr.io/you/quikcast:1 .and push it), enter that image name instead. This is faster to deploy and avoids compiling on the server.
- GitHub / Git: connect the Quikcast repository, pick the branch, and set Build Type to Dockerfile with path
Do not deploy yet. It needs a config first.
2. Add the config and secrets
The image starts with an example config that expects a password file, so it fails until you provide one. In the application, open Advanced → Mounts and add File Mounts.
File mount 1: the config
| Field | Value |
|---|---|
| File path | quikcast.toml |
| Mount path | /etc/quikcast/quikcast.toml |
listen = "0.0.0.0:8000" # must be 0.0.0.0 inside a container
admin_listen = "127.0.0.1:9090" # stays private
[trusted_proxies] # Traefik's address, so listeners show their real IP
ips = ["10.0.0.0/8", "172.16.0.0/12"]
[ui] # optional: the web console at /console
enabled = true
mode = "private"
username = "admin"
password_file = "secrets/ui-password"
public_url = "https://radio.example.com"
[[mounts]]
path = "/radio.mp3"
username = "source"
secret_file = "secrets/radio-source"File mounts 2 and 3: the secrets. Paths are relative to the config file, so secrets/radio-source means /etc/quikcast/secrets/radio-source.
| File path | Mount path | Content |
|---|---|---|
radio-source | /etc/quikcast/secrets/radio-source | the encoder password (16+ characters) |
ui-password | /etc/quikcast/secrets/ui-password | the console password (15+ characters) |
Generate good values on your own machine:
openssl rand -hex 16 # encoder password
openssl rand -base64 24 # console passwordNo console? Skip it
Leave out the [ui] block and the ui-password mount. Everything else works the same.
3. Add the domain
Open the Domains tab and add:
| Field | Value |
|---|---|
| Host | radio.example.com |
| Path | / |
| Container port | 8000 |
| HTTPS | on |
| Certificate | Let's Encrypt |
Make sure the domain's DNS record points at your Dokploy server first, or the certificate request fails.
4. Deploy
Press Deploy and watch the Logs tab. You are looking for:
quikcast accepting connections listen=0.0.0.0:8000 admin_listen=127.0.0.1:9090The Deployments tab should show a healthy container. The image has its own health check, so Dokploy flags it if the server stops answering.
5. Connect an encoder and listen
Use the values from Connect an encoder:
| Setting | Value |
|---|---|
| Host | radio.example.com |
| Port | 443, with TLS/SSL enabled |
| Mountpoint | /radio.mp3 |
| Username | source |
| Password | the contents of radio-source |
Listeners open https://radio.example.com/radio.mp3. The console, if you enabled it, is at https://radio.example.com/console.
If your encoder fails through the domain
Some encoders use the older Icecast SOURCE request, which an HTTP proxy such as Traefik may reject. If an encoder works against the server directly but not through the domain, publish the port for encoders only:
- In Advanced → Ports add a port: published
8000, target8000, protocol TCP. - Point the encoder at
your-server-ip:8000over plain HTTP.
Listeners keep using HTTPS through the domain. That direct port is unencrypted, so use a strong encoder password and, if you can, restrict it by firewall to your encoder's address or add [mounts.source_access] rules (see Limit who can listen).
Run it
Change settings
Edit the file mount's content (the config or a secret) and press Save, then either:
- Redeploy. Simple, but it disconnects everyone briefly. Encoders and players reconnect on their own.
- Reload without disconnecting. Open the application's Terminal tab and run
kill -HUP 1. Quikcast is the container's main process, so this applies passwords, access rules, relays and the console settings instantly. Listeners and encoders stay connected. See what can be reloaded.
A file mount only changes inside the container after a redeploy or restart, so if a reload does not pick up your change, redeploy.
Check health and metrics
The admin port is private, so use the Terminal tab:
curl -s http://127.0.0.1:9090/health/ready
curl -s http://127.0.0.1:9090/metrics | headSize the container
Audio uses little CPU, but bandwidth adds up: 1,000 listeners at 128 kbit/s is about 128 Mbit/s outbound. In Advanced → Resources you can cap CPU and memory. Real memory use sits well below retained_audio_budget, which is only a startup ceiling, so watch it in Dokploy's monitoring and leave headroom before setting a limit. See Capacity and limits.
Nothing to back up
All runtime state is in memory. Keep a copy of your config and secrets, which live in the file mounts.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
Container restarts; logs say failed to read ... secrets/radio-source | The secret file mount is missing or its mount path is wrong. It must be /etc/quikcast/secrets/radio-source for secret_file = "secrets/radio-source". |
Logs say Permission denied on a secret | The container runs as a non-root user. Check the file's mode on the host copy that Dokploy created and make it readable by others (chmod 644). |
Domain shows 502 Bad Gateway | The container is not healthy yet, or the domain's container port is not 8000, or listen is not 0.0.0.0:8000. |
404 page not found from Traefik | The domain is not attached to this application, or DNS points somewhere else. |
| HTTPS certificate error | DNS does not point at the server yet, or ports 80/443 are blocked. Let's Encrypt needs both. |
| Listeners all show the same IP | Add Traefik's network to [trusted_proxies] ips. Docker networks are usually 10.0.0.0/8 or 172.16.0.0/12. |
Startup says retained audio budget cannot cover admission reservations | Your limits need more memory than retained_audio_budget allows. Lower max_listeners under [limits] or raise the budget. See Capacity and limits. |
| Stream cuts off after a few minutes | A proxy timeout in front of Traefik (a CDN or load balancer). Long-lived audio needs long timeouts and no buffering. |
| Console login loops | Use the HTTPS domain. The session cookie is Secure, so browsers drop it over plain HTTP. |
Compose instead of an application
Prefer Compose? Create a Compose service, paste the repository's docker-compose.yml, add the same config and secrets as bind mounts or files, and attach the domain with container port 8000. The application route above is simpler.