Skip to content

Installation

Jump to bottom
Ken Ellorando edited this page May 9, 2024 · 17 revisions

This page describes various methods for installing and deploying a Cadence Radio 5.x stack.

Method 1 (Recommended): Installation Script

The recommended way to install Cadence is to use the ./install.sh script. All regular users are advised to install this way because it simplifies and semi-automates the configuration process. It converts the .example configuration files and Docker Compose file into live ones, prompts you for necessary variables, and modifies everything accordingly.

Requirements

You must have Docker and Docker Compose installed.

Running the Script

Simply give execute permissions to the script and run:

chmod +x install.sh
./install.sh

The script will launch an interactive series of prompts that will ask you for configuration data. The Cadence stack will automatically launch after the last prompt is provided.

Prompts

[1/5] Absolute Path to Music

Description: The absolute path (the full file path starting with a /) of an accessible directory containing audio files such as .mp3 or .flac. The target is not recursively searched, so only files at the base of the target will be added, not those in any subdirectory.

Examples: /music/, /home/ken/Music/

[2/5] Stream Host Address

Description: The Cadence stack launches two publicly accessible servers: an Icecast server which broadcasts audio, and a web server which serves the frontend UI. The value you provide here will be set the name of the Icecast server, then injected back into the frontend to connect it back to Icecast. The value you provide here will depend on the audience you intend to broadcast to.

Examples:

  • Using localhost:8000 will set the frontend to always load a stream from localhost:8000. In other words, you cannot use a localhost value if you want to have a radio available beyond the machine it is running on.
  • Using a home NAT IP like 192.168.0.11:8000 will set the frontend to always load a stream from 192.168.0.11:8000. The radio can be accessible from other devices on the same local network.
  • Using a public DNS name like myradio.mydomain.com will set the frontend to load from that URL. On my demo site, I use the subdomain stream.cadenceradio.com here.

The Cadence frontend will infer the stream URL protocol (http, https) based on how the site is accessed, so if you connect to the UI over http, it will attempt to load the stream over http.

[3/5] Rate Limiter Timeout

Description: Cadence has a simple built-in rate limiter which can prevent single IP addresses from making more than one song request in some time-frame. This is provided to help prevent anyone from requesting something a hundred times, clogging the request queue. The value you provide here is an integer which represents the time in seconds a listener must wait after making a request before they can make another one. You can set this to 0 to disable.

Examples: 180 (3 minutes), 0 (disable rate limiting)

[4/5] Service Password

Description: This is a password which will allow your Cadence stream and source services to talk to each other. This can be any non-zero length value. Your input is hidden as you type.

Examples: (anything, as long as the value is not blank)

[5/5] Enable Reverse Proxy

Description: Cadence ships with an nginx container which automatically sets up a reverse proxy to route external traffic hitting your server to the correct Cadence services. You will first be prompted to disable or enable this feature. If you are not bringing your own domain names (e.g. you are hosting locally or on your local network only) then you should disable this. If you are running a server with your own reverse proxy, you may also want to disable this.

Examples: A reverse proxy will be configured if you respond y or Y. A prompt will ask you to provide the domain name you intend to host the web UI on. For my demo site, I provide cadenceradio.com here.

If you answer anything other than y or Y, setup will skip reverse proxy installation.

Post-Installation

After you initially run the script, your configuration settings will be saved to local files and you may simply run docker compose up to start the stack without needing to use the script again. Of course, you may run ./install.sh at any time again to reconfigure.

Method 2: Manual Installation

If you don't want to use the script or are unable to use it, you can still manually execute the same steps that the script performs using the steps below.

Requirements

  1. You must have Docker and Docker Compose installed.

Manual Installation Steps

  1. You must first create a copy of every file in the config/ directory, removing the .example extension from each file.
  2. Edit config/cadence.env
    1. Change all instances of CADENCE_PASS_EXAMPLE to a new password.
    2. Change all instances of CADENCE_PATH_EXAMPLE to an absolute path which contains music files (.mp3, .flac) for play. The target is not recursively searched.
    3. Change all instances of CADENCE_RATE_EXAMPLE to an integer that sets the song request cooldown period in seconds. Set this value to 0 to disable rate limiting.
  3. Edit config/icecast.xml
    1. Change all instances of CADENCE_PASS_EXAMPLE to a new password.
    2. Change CADENCE_HOST_EXAMPLE, within <hostname>, to a URL you expect your audience to connect to. This value is what is set in the UI's stream source. This may be a DNS name or a public or private IP address. You can leave the default value localhost if your radio is meant to be accessible locally only.
  4. Edit config/liquidsoap.liq
    1. Change all instances of CADENCE_PASS_EXAMPLE to a new password.
    2. If you changed CADENCE_PATH_EXAMPLE in step 2, change any instances of the default value /music/ to match it here.
  5. Edit docker-compose.yml
    1. If you changed CADENCE_PATH_EXAMPLE in step 2, change any instances of the Volumes defined, replacing /music:/music with /YOURDIR:/YOURDIR.
  6. (Optional) Edit config/nginx.conf
    1. For advanced users deploying Cadence to a server with DNS, Cadence ships with a reverse proxy that can forward requests based on domain-name to backend services. Simply configure the server_name values with your domain names. The stream server domain should match the value you set in step 2.
  7. Run docker compose up (or docker compose --profile nginx up to start the stack with a reverse proxy).
Clone this wiki locally