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 ​

  1. In Dokploy, open a Project and choose Create Service → Application.
  2. 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.

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

FieldValue
File pathquikcast.toml
Mount path/etc/quikcast/quikcast.toml
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 pathMount pathContent
radio-source/etc/quikcast/secrets/radio-sourcethe encoder password (16+ characters)
ui-password/etc/quikcast/secrets/ui-passwordthe console password (15+ characters)

Generate good values on your own machine:

sh
openssl rand -hex 16     # encoder password
openssl rand -base64 24  # console password

No 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:

FieldValue
Hostradio.example.com
Path/
Container port8000
HTTPSon
CertificateLet'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:

text
quikcast accepting connections listen=0.0.0.0:8000 admin_listen=127.0.0.1:9090

The 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:

SettingValue
Hostradio.example.com
Port443, with TLS/SSL enabled
Mountpoint/radio.mp3
Usernamesource
Passwordthe 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:

  1. In Advanced → Ports add a port: published 8000, target 8000, protocol TCP.
  2. Point the encoder at your-server-ip:8000 over 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:

sh
curl -s http://127.0.0.1:9090/health/ready
curl -s http://127.0.0.1:9090/metrics | head

Size 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 ​

SymptomCause and fix
Container restarts; logs say failed to read ... secrets/radio-sourceThe 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 secretThe 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 GatewayThe 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 TraefikThe domain is not attached to this application, or DNS points somewhere else.
HTTPS certificate errorDNS does not point at the server yet, or ports 80/443 are blocked. Let's Encrypt needs both.
Listeners all show the same IPAdd 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 reservationsYour 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 minutesA proxy timeout in front of Traefik (a CDN or load balancer). Long-lived audio needs long timeouts and no buffering.
Console login loopsUse 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.