How to
install Freo.

Step 01

Choose a fresh server

A virtual private server (VPS) is a computer you rent from a hosting provider. It stays online so your station can broadcast when your own computer is off. In your provider’s dashboard, create a new Ubuntu 24.04 LTS server with an x86_64/AMD64 processor. Choose a plain operating-system image, not a web-hosting panel, Docker image, or ARM server.

• Use an empty server dedicated to Freo. An existing Freo installation or PostgreSQL database is not a fresh target.
• You need administrator access: a root login or a user allowed to run sudo.
• Allow storage for the application, downloaded and extracted packages, your music, and backups. CPU and memory needs grow with stations and audio processing; no universal minimum size is published with this release. Your provider can help size the server.
• Check the provider’s data-transfer allowance. As an example, a 128 kbps stream uses about 58 MB per listener-hour before overhead; ten listeners for a month can use roughly 415 GB.
• Have some MP3, WAV, M4A or FLAC music you have permission to broadcast.

Write down these details before continuing:

Ready: You have a fresh supported server, its login details, and access to your domain’s DNS settings.

Step 02

Connect and prepare

On Windows, open Windows Terminal or PowerShell. On macOS or Linux, open Terminal. SSH opens a command line on the remote server. Replace both uppercase placeholders:

ssh YOUR_SSH_USER@YOUR_SERVER_IP

If your provider requires a key file, use ssh -i /path/to/your/private-key YOUR_SSH_USER@YOUR_SERVER_IP with the actual local key path. If it uses a different SSH port, add -p PORT. Compare a first-connection host fingerprint with your provider’s console before accepting it. Passwords are not shown while you type; that is normal.

You are now typing on the server. Confirm its name matches the server you just created:

hostname
cat /etc/os-release
uname -m
sudo -v

Look for Ubuntu, VERSION_ID="24.04", and x86_64. sudo grants administrator privileges for a command. If you are already logged in as root and sudo is unavailable, omit that word; otherwise obtain a sudo-capable account from your provider.

Install the small tools used below. This does not install Freo yet:

sudo apt-get update
sudo apt-get install -y ca-certificates curl python3 dnsutils ufw tmux less

Check the clock and available disk space:

timedatectl status
df -h /

The clock should show the correct date/time and be synchronized. If not, fix time synchronization with your provider before certificate or download checks. Make sure there is free space for your packages and music.

Ready: You are on the intended Ubuntu 24.04 x86_64 server, commands complete without errors, and you have administrator access.

Step 03

Give your station a secure address

HTTPS protects your admin login and is required for a remote browser microphone. Set it up during installation. You need a domain or subdomain that belongs to you.

1. Open the DNS settings for your domain. Add an A record named radio, pointing to your new server’s public IPv4 address. For a domain such as example.com, this creates radio.example.com.
2. Use ordinary DNS routing during setup. If your DNS service offers a proxy or CDN mode, choose DNS-only for this hostname.
3. For this IPv4 walkthrough, remove a stale AAAA record for that radio hostname unless IPv6 is correctly configured on the same server. Do not change unrelated records for your domain.
4. Wait for DNS to update, then check your actual radio hostname:

dig +short A radio.example.com
dig +short AAAA radio.example.com

The A answer must be your new server’s public IPv4 address. With IPv4-only setup, the AAAA answer should be empty. A matching result is a useful check, but DNS caches elsewhere may still need time.

In the hosting dashboard’s firewall (sometimes called a security group), allow:

Allow outbound DNS, HTTPS and package-repository access. The installer needs GitHub, Ubuntu/Xiph repositories and Freo Live. Database and internal audio ports do not need public access. Live Mic has separate network requirements; get basic music playback working first.

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw show added

sudo ufw enable
sudo ufw status

Ready: DNS points at your server, SSH still works, and inbound 80/443 are allowed in both cloud and host firewalls. Port 80 must remain reachable for certificate validation and renewal.

Step 04

Download and check the installer

Download on the new server, not your laptop. Start a tmux session first; it keeps the installation running if your SSH connection drops:

tmux new -s freo-setup

A new terminal opens inside the existing one. Continue there. If you disconnect later, SSH back in as the same user and run tmux attach -t freo-setup. If it says no session exists, check the installation’s outcome before starting again.

mkdir -p "$HOME/freo-setup"
cd "$HOME/freo-setup"
curl --fail --silent --show-error --proto '=https' \
  --connect-timeout 15 --max-time 120 \
  --output freo-install.sh.part https://freo.live/install &&
  mv freo-install.sh.part freo-install.sh

If the download fails, stop. After a successful download, check the approved installer checksum:

printf '%s  %s\n' '0e494e6b07af6331ff27894515fd648a71da1c1769e3bdd257cb396dc65bdf9a' 'freo-install.sh' | sha256sum --check

Expect freo-install.sh: OK. A mismatch means do not run it; obtain the current approved instructions. This checksum checks the script against this guide. The later Freo package signature is verified separately by the installer.

bash -n freo-install.sh
less freo-install.sh

Ready: The complete script has downloaded and its checksum says OK. Freo has not been installed yet.

Step 05

Install Freo

Replace radio.example.com with the hostname you checked in step 3 and you@example.com with your real certificate email. Use only the hostname: no https://, slash, or port.

sudo bash freo-install.sh \
  --domain radio.example.com \
  --https --email you@example.com

The installer shows the server name, address, operating system, installer version and selected Freo version. Check that this is your new server. At Continue? [y/N], enter y only if the details are right. It may separately ask to install missing signature-verification tools.

It downloads the stable GitHub release, verifies its publisher signature and package contents, then installs the application, database and radio services. It also requests an HTTPS certificate for your hostname. Keep the session open and wait for completion; package downloads and processing can take time.

sudo bash freo-install.sh --domain YOUR_SERVER_IP

Success: The installer reports that Freo is installed and prints your /admin/login address. Keep the printed private diagnostics path. If it stops with an error, go to troubleshooting; do not repeatedly reinstall over partial state.

Step 06

Make the first login yours

On your own computer, open the address printed by the installer in a web browser, such as https://radio.example.com/admin/login. Use your actual hostname. For the HTTP alternative, use http://YOUR_SERVER_IP/admin/login.

The approved release’s first login is username admin and temporary password IAmOnTheAir. Immediately complete the required setup with your email and a new private password of at least 16 characters. Save it in a password manager. The temporary password then stops working.

For HTTPS, the browser should show a secure connection without a certificate warning. Do not enter credentials through an unexpected certificate warning; check DNS and the installer’s certificate result first.

Success: You can sign in with your new account and see Freo’s administration workspace. An empty station list is normal—no demo stations or music are installed.

Step 07

Put your first music on air

Start with one station and a small set of music. Keep the same station selected while following these steps.

1. Add a station. Open Stations → Add station. Give it a name and a Station ID such as my-radio (lowercase letters, numbers and hyphens). Choose your timezone, then select Add station. The ID forms part of the listening URL and cannot be changed later. Wait for provisioning to finish; if it fails, inspect the displayed error before retrying.
2. Import music. Open the station’s Music workspace and its import page. Choose files or a folder, review the selection, then select Import music. Wait until processing completes. Check that the songs are enabled for broadcast; do not choose Keep disabled for this first test. Preview a song to confirm the audio is right.
3. Make a small playlist. Open Playlists, choose + New, enter a name, choose Straight (in order) or Random, and save. Use + Add music to add your imported songs. Confirm the playlist contains playable songs.
4. Choose continuous playback. Open Station Control → Open Simple. In the library, find your playlist and place it in the Just play this selection. Save the selection. Return to Station Control, choose Use Simple, and confirm the mode change if prompted. Simple plays the chosen source continuously; you can add scheduled shows later.
5. Turn broadcasting on. In Station Control, turn MASTER BROADCAST ON. Wait for the change to be applied and the observed station status to update. An ON switch alone is not proof that music is playing: an empty or unavailable source can produce a fallback tone.
6. Listen as a visitor. Open your station’s public player, such as https://radio.example.com/player/my-radio, in another browser or on your phone. Replace both the hostname and station ID. Press Play; browsers usually require this click. Confirm you hear music, not just tone. Try mobile data to check access from outside your network.

Success: The public player plays your chosen music and you see confirmed playback in Freo. Your browser’s monitor button only controls local listening; MASTER BROADCAST controls whether the station broadcasts.

Remote microphone input is a separate feature with an optional gateway and WebRTC network setup. Once basic radio works, follow the Live Mic guide.

Step 08

Check it, then test a reboot

Back in your server terminal, run the release’s validation script and list any failed services:

cd /opt/freo
sudo bash scripts/validate-install.sh
sudo systemctl --failed --no-pager

Look for a line beginning Freo validation passed. Ideally the service list shows no failed units. Investigate a failed validation or failed unit rather than assuming the website loading proves everything works.

For an HTTPS installation, check certificate renewal too:

sudo certbot renew --dry-run

Expect successful renewal simulation for your radio certificate. When you are ready for a brief interruption, leave your station broadcasting and reboot:

sudo reboot

Your SSH connection will close. Wait for the server to return, reconnect using step 2, and run the validation commands again. Open the admin page and public player and press Play. Confirm your running station comes back without starting it manually, with your music and settings intact.

Finished: Validation passes, the HTTPS certificate works, and music plays externally before and after reboot.

Step 09

Look after your station

• Arrange backups before building a large library. Follow the backup and recovery guide for your database, music, configuration and installation identity. Store a protected copy away from this server and test restoration on a separate machine. A provider snapshot alone is not a verified application backup.
• Use the upgrade path for updates. The primary administrator can access Software management. Read the release notes and recovery procedure before upgrading. Do not use the fresh installer on an existing station.
• Registration is optional. Create a Freo Live account if you want to link and manage your installation. Automatic reporting includes the running version and aggregate station information; public directory listing needs a separate opt-in. Version status can remain Unknown until a successful heartbeat, normally hourly. Do not replace identity files or credentials to force a status.
• Keep access private. Protect server keys and admin credentials. Share only reviewed, relevant diagnostic output when requesting help; never share .env, passwords, private keys, bearer tokens or identity files.

Freo is source-available and free for up to three stations under its published license. Hosting, domains and the rights to broadcast your music are separate. See licensing for details.