How to Install AzuraCast Radio on Your Own VPS: A Complete Step‑by‑Step Guide

Introduction

In an era where streaming services dominate music consumption, the allure of running your own internet radio station remains strong. Whether you want to broadcast a niche music genre, host a talk show, or simply share your curated playlists with the world, self‑hosted solutions give you full control over content, branding, and monetization. AzuraCast has emerged as one of the most popular open‑source platforms for this purpose, combining a polished web interface with powerful backend components like Icecast and Liquidsoap. This guide walks you through installing AzuraCast on a virtual private server (VPS) from scratch, covering everything from server preparation to going live, with tips for security, automation, and future scaling.

What Is AzuraCast?

AzuraCast is a self‑hosted, Docker‑based internet radio station management system. It provides a modern, responsive dashboard for managing media libraries, scheduling shows, configuring AutoDJ, and monitoring listener statistics. Under the hood, it orchestrates several containers: a web panel (NGINX + PHP‑FPM), Icecast for streaming, Liquidsoap for audio processing, and optional services such as MariaDB for data storage and Redis for caching. Because it relies on Docker, the installation process is largely distribution‑agnostic, making it suitable for Ubuntu, Debian, CentOS, or any other Linux VPS that can run Docker Engine.

The project began in 2017 as a response to the complexity of legacy radio automation tools. Over the years, the community has added features like SSL automation via Let’s Encrypt, remote DJ login, API access, and a growing marketplace of plugins. As of 2024, AzuraCast powers thousands of stations worldwide, ranging from hobbyist hobbyists to commercial broadcasters.

Why Self‑Host Your Radio Station?

Third‑party hosting services offer convenience, but they come with limitations: recurring monthly fees, restricted customization, potential content censorship, and dependency on the provider’s uptime. By contrast, a self‑hosted AzuraCast instance gives you:

Full control: You decide what audio formats, bitrates, and metadata are broadcast.
Cost efficiency: After the initial VPS expense, there are no per‑listener or per‑hour charges.
Scalability: You can upgrade your VPS or add additional servers for load balancing as your audience grows.
Privacy: Listener statistics and DJ credentials remain on your own infrastructure.
Customization: You can install plugins, theme the panel, or integrate with external authentication systems.

Of course, self‑hosting also means you assume responsibility for server maintenance, security patches, and backups. The following steps aim to minimize operational overhead while maximizing reliability.

Prerequisites and Planning

Before touching the command line, it’s wise to outline the resources and decisions you’ll need.

Hardware Requirements

AzuraCast is lightweight, but the actual demands depend on your anticipated listener count and audio bitrate. A baseline VPS should meet:

1 GB RAM (2 GB recommended for modest traffic)
1 CPU core (2 + cores for higher concurrent listeners)
20 GB SSD storage (more if you plan a large media library)
1 TB monthly bandwidth (adjust based on expected listener hours)

If you intend to stream at 320 kbps MP3 to 100 simultaneous listeners, you’ll need roughly 32 Mbps of upstream bandwidth, plus overhead for transcoding and web traffic.

Operating System Choice

AzuraCast’s official install script supports Ubuntu 20.04 LTS, Ubuntu 22.04 LTS, Debian 10/11, and CentOS 7/8. For simplicity and long‑term support, Ubuntu 22.04 LTS is a solid choice. Ensure you have a fresh installation with root access (or a sudo‑enabled user).

Domain Name and DNS

While you can access the panel via the server’s IP address, a domain name is essential for SSL certificates and a professional appearance. Purchase a domain from any registrar, then create an A record pointing to your VPS’s public IPv4 address. If you plan to use IPv6, add an AAAA record as well.

Ports to Open

AzuraCast uses several ports:

80/tcp – HTTP (redirected to HTTPS)
443/tcp – HTTPS (web panel and API)
8000/tcp – Icecast streaming port (optional, can be proxied)
8001/tcp – Liquidsoap control (internal, not exposed)
21/tcp – FTP (if you enable the optional FTP media upload)
22/tcp – SSH (administrative access)

You can keep the firewall minimal: allow SSH, HTTP, HTTPS, and the streaming port if you expose Icecast directly; otherwise, rely on the reverse proxy (NGINX) to handle ports 80 and 443 only.

Step 1: Prepare the VPS

Log in to your VPS via SSH as root (or a user with sudo privileges). Begin by updating the package index and upgrading installed packages.

sudo apt update && sudo apt upgrade -y

On CentOS, replace with sudo yum update -y or sudo dnf upgrade -y depending on the version.

Next, create a non‑root user for day‑to‑day administration (optional but recommended).

sudo adduser azurauser
sudo usermod -aG sudo azurauser

Switch to the new user:

su - azurauser

Ensure the system clock is accurate; install chrony or ntp if needed.

sudo apt install chrony -y
sudo systemctl enable --now chronyd

Finally, set a hostname that matches your domain (or a subdomain).

sudo hostnamectl set-hostname radio.example.com

Add the hostname to /etc/hosts for local resolution:

127.0.0.1   radio.example.com

Step 2: Install Docker Engine and Docker Compose

AzuraCast relies on Docker to isolate its components. The installation steps below follow the official Docker repository method, ensuring you get the latest stable version.

Remove Old Versions (if any)

sudo apt-get remove docker docker-engine docker.io containerd runc

Set Up the Repository

sudo apt-get install ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify the installation:

sudo docker run --hello-world

You should see a friendly message from Docker confirming it works.

Manage Docker as a Non‑Root User (Optional)

To avoid prefixing every command with sudo, add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Log out and back in for the group change to take effect.

Step 3: Deploy AzuraCast via the Official Installer

The AzuraCast team provides a convenient bash script that handles Docker Compose file generation, container pulls, and initial configuration. This method is the fastest way to get a working station.

Download the installer:

curl -fsSL https://raw.githubusercontent.com/AzuraCast/AzuraCast/master/docker-compose.sh -o azuracast_setup.sh

Make it executable:

chmod +x azuracast_setup.sh

Run the script, specifying your desired installation directory (e.g., ~/azuracast) and the hostname you set earlier.

./azuracast_setup.sh install -h radio.example.com -p ~/azuracast

The script will:

Create the target directory and a docker-compose.yml file.
Pull the required Docker images (AzuraCast web, Icecast, Liquidsoap, etc.).
Generate a secure random password for the MariaDB root user and store it in .env.
Start the containers in detached mode.

Depending on your VPS speed, this step may take a few minutes. Once completed, you should see output similar to:

AzuraCast has been successfully installed!

Visit http://radio.example.com to begin the setup wizard.

If you prefer a manual approach, you can clone the GitHub repository and edit the docker-compose.yml yourself, but the installer covers 95 % of use cases.

Step 4: Configure SSL with Let’s Encrypt

AzuraCast includes built‑in Let’s Encrypt automation via the azura-letsencrypt companion container. To enable HTTPS, you need to point your domain to the server and allow the validator to reach port 80.

First, ensure the web panel is accessible via HTTP:

curl -I http://radio.example.com

You should receive a 200 OK response (possibly a redirect to the setup wizard).

Next, run the SSL provision command:

docker exec azuracast_web azura-letsencrypt

The container will:

Request a certificate from Let’s Encrypt for your domain.
Configure the NGINX reverse proxy to use the certificate.
Set up automatic renewal via a cron job inside the container.

Upon success, you’ll see output indicating the certificate has been obtained and the web server reloaded.

Now test HTTPS:

curl -I https://radio.example.com

You should see a 200 OK and the Strict-Transport-Security header if HSTS is enabled.

If you encounter errors (e.g., timeout, connection refused), double‑check:

Your domain’s A record points to the correct IP.
Port 80 is open in the firewall (sudo ufw allow 80/tcp if using UFW).
No other service is already binding to port 80.

Step 5: Complete the Initial Setup Wizard

Open your browser and navigate to https://radio.example.com. You’ll be greeted by the AzuraCast setup wizard, which guides you through:

Administrator account: Create a username, email, and password for the primary admin.
Station details: Enter your station name, description, genre, timezone, and optional social media links.
Stream configuration: Choose the default audio format (MP3, AAC, OGG), bitrate, and whether to enable AutoDJ.
Media storage: Decide whether to store uploaded media locally (default) or use an external mount (e.g., Block Storage, NFS).
Optional features: Enable FTP access, API access, or the public player widget.

After submitting the form, AzuraCast will finalize the configuration, restart relevant containers, and log you into the dashboard.

Take note of the admin credentials; you’ll need them for future logins and API access.

Step 6: Upload Media and Build Your Library

A radio station is only as good as its music library. AzuraCast supports bulk uploading via the web interface, FTP, or even rsync if you mount external storage.

Using the Web Interface

In the dashboard, go to Media → Add Media. You can drag‑and‑drop files or click to browse. Supported formats include MP3, AAC, FLAC, WAV, and OGG. As files upload, AzuraCast extracts metadata (ID3 tags) and generates waveforms for the now‑playing display.

Using FTP (Optional)

If you enabled FTP during setup, you can connect with an FTP client (e.g., FileZilla) using the credentials stored in ~/azuracast/.env under AZURACAST_FTP_USER and AZURACAST_FTP_PASS. Upload files to the /media directory inside the container; they will be automatically scanned and imported.

Metadata and Categorization

After upload, visit Media → Edit to adjust:

Title, artist, album, year, genre.
Custom categories (e.g., “Jazz”, “Podcasts”, “Promos”).
Whether the track is eligible for AutoDJ rotation.
Listener‑visible artwork (upload a cover image).

Proper tagging improves AutoDJ accuracy and helps listeners discover content via the public API.

Step 7: Configure AutoDJ and Scheduling

AutoDJ is the engine that keeps your stream live when no live DJ is connected. It selects tracks based on rules, weightings, and scheduled events.

Basic AutoDJ Settings

Navigate to Manage Station → AutoDJ. Here you can:

Set the playback order (sequential, random, weighted random).
Define fallback tracks for when the queue empties.
Enable crossfading and adjust the crossfade duration (seconds).
Set silence detection thresholds (useful for detecting dead air).

Creating Playlists and Rotations

Under Media → Playlists, create one or more playlists (e.g., “Top 40”, “Chillout”, “News”). Assign tracks to each playlist and set a weighting that determines how often songs from that playlist are selected.

For time‑based programming, use Schedule → Events. You can create recurring events (e.g., a weekly show every Friday at 19:00) or one‑time events. Each event can:

Switch to a specific DJ source (Live input, remote DJ, or a predefined playlist).
Change the stream bitrate or enable/disable AutoDJ.
Run a command or script via the shell_exec feature (advanced).

Testing the AutoDJ

From the dashboard, click Start AutoDJ. You should see the stream status change to “Online” and the now‑playing widget display a track from your library. Use the public player URL (e.g., https://radio.example.com/widget) to listen in a browser or external player.

Step 8: Enable Remote DJ Access

Many stations rely on DJs who broadcast from home studios or mobile setups. AzuraCast supports two primary methods: the built‑in “DJ Login” and external ICEcast source connections.

Built‑In DJ Login

In Manage Station → DJ Accounts, create accounts for each DJ. Specify a username, password, and optionally restrict the IP address or user agent. DJs can then log in via https://radio.example.com/dj using a web‑based broadcaster (e.g., Mixxx, BUTT, or the AzuraCast Web DJ).

The web DJ interface provides:

Simple microphone and desktop audio capture.
Real‑time level meters.
Ability to insert jingles or pre‑recorded segments.

External ICEcast Source

If DJs prefer their own encoding software (e.g., SAM Broadcamp, Rivendell, or OBS with Icecast output), provide them with the following connection details:

Host: radio.example.com (or your server’s IP)
Port: 8000 (Icecast)
Mount point: /live (or a custom mount you create under Manage Station → Mounts)
Password: The source password found in ~/azuracast/.env under AZURACAST_ICECAST_SOURCE_PASSWORD.

Encourage DJs to use encrypted connections (e.g., TLS) if their software supports it; otherwise, consider placing Icecast behind a VPN or using Stingray for added security.

Step 9: Hardening Security and Monitoring

Running a public‑facing service invites attention. Below are essential hardening steps.

Firewall Hardening

If you’re using UFW (Uncomplicated Firewall):

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh/tcp
sudo ufw allow http/tcp
sudo ufw allow https/tcp
sudo ufw allow 8000/tcp   # Only if you expose Icecast directly
sudo ufw enable

Consider installing fail2ban to block brute‑force SSH and web panel attempts:

sudo apt install fail2ban -y
sudo systemctl enable --now fail2ban

Regular Updates

AzuraCast releases updates frequently. To update your instance:

cd ~/azuracast
./azuracast_update.sh

The update script will pull new Docker images, restart containers, and apply any database migrations.

For Docker itself, follow the official upgrade instructions for your distribution.

Backups

AzuraCast stores its data in three primary locations:

The MariaDB database (container azuracast_db).
The media library (bind‑mounted to ~/azuracast/media by default).
The ~/azuracast configuration directory (contains .env, SSL certificates, and custom hooks).

A simple backup strategy:

Stop the containers: docker compose down.
Create a tarball of the ~/azuracast directory.
Optionally, dump the database: docker exec azuracast_db mysqldump -u root -p$MYSQL_ROOT_PASSWORD azuracast > azuracast_db.sql.
Restart containers: docker compose up -d.

Store the backup off‑site (e.g., on a separate VPS, cloud storage, or external hard drive). Automate the process with a cron job.

Monitoring and Logging

AzuraCast’s dashboard includes a Overview panel with listener count, bandwidth usage, and container health. For deeper insight:

View logs: docker compose logs -f azuracast_web (web panel) or azuracast_icecast (streaming server).
Use watch to monitor resource usage: watch -n 5 docker stats.
Consider integrating with Prometheus + Grafana if you need long‑term metrics.

Step 10: Going Live and Promoting Your Station

With the technical foundation in place, it’s time to attract listeners.

Testing the Stream

Open the public player (https://radio.example.com/widget) in a separate browser tab or use VLC with the URL https://radio.example.com:8000/stream (if you exposed Icecast directly). Verify:

Audio plays without buffering or dropouts.
Metadata (song title, artist) updates correctly.
Stream bitrate matches your configured setting.
Listener count increments when you open the player.

Sharing the Widget

AzuraCast provides an embeddable HTML snippet under Widget → Embed Code. Copy the iframe code and paste it into your website, blog, or social media page.

Leveraging Social Media and Directories

Submit your station to directories such as:

TuneIn
StreamFinder
Radio.net
Shoutcast.com (if applicable)
Google Podcasts (for talk‑show content)

Create a consistent branding package: logo, banner, and color scheme that matches your AzuraCast theme.

Engaging Your Audience

Enable the built‑in chat widget or integrate a third‑party chat (e.g., Discord widget) to foster community. Consider scheduling regular listener polls, song requests, or live Q&A sessions via the remote DJ interface.

Maintenance, Troubleshooting, and Future Enhancements

Even a well‑configured station will need occasional attention.

Common Issues

502 Bad Gateway: Usually indicates the web panel container is not responding. Check logs with docker compose logs azuracast_web and ensure the container is healthy (docker compose ps).
No Audio / Silence: Verify AutoDJ is running, the media library is scanned, and the Icecast source password matches the DJ’s encoder settings.
SSL Renewal Failures: Ensure port 80 remains open and that no other service (e.g., Apache) is interfering. You can manually renew with docker exec azuracast_web azura-letsencrypt renew.
High CPU Usage: Liquidsoap can be CPU‑intensive at high bitrates or with many concurrent listeners. Consider lowering the bitrate, enabling Opus (more efficient), or upgrading your VPS CPU.

Performance Tuning

Enable OPUS streaming for better quality at lower bitrates (requires Icecast 2.4+ and compatible player).
Use ezstream or ices for fixed‑bitrate relay if you need to rebroadcast an external feed.
Offload media storage to a block storage volume (e.g., AWS Lightsail Block Storage, DigitalOcean Spaces) to keep the VPS root disk lean.

Exploring the API and Integrations

AzuraCast exposes a RESTful API (documented at https://radio.example.com/api/docs) that lets you:

Programmatically add media, create playlists, and trigger events.
Build custom dashboards or mobile apps.
Integrate with home‑automation platforms (e.g., trigger a stream when motion is detected).

Additionally, the Marketplace within the dashboard offers community‑maintained plugins for features like:

Advanced DJ authentication (LDAP, OAuth).
Automatic loudness normalization (EBU R128).
Dynamic ad insertion.
Multi‑tenant station hosting.

Conclusion

Installing AzuraCast on your own VPS puts the power of a professional internet radio station firmly in your hands. By following the steps outlined above—preparing the server, deploying Docker, securing the panel with SSL, configuring AutoDJ, and enabling remote DJ access—you can launch a reliable, scalable broadcast platform with minimal ongoing cost. The combination of open‑source flexibility, a vibrant community, and a modern web interface means you can tailor the station to your exact vision, whether that’s showcasing underground music, hosting a talk show, or delivering a branded audio experience for a business.

As you grow, remember to monitor performance, keep software up to date, and back up your data regularly. With those practices in place, your station can run smoothly for years to come, reaching listeners across the globe and evolving alongside advances in streaming technology.