Skip to content

Unified Installer

Jump to bottom
Anjeleno edited this page Jun 29, 2026 · 8 revisions

Unified Installer

An Ansible playbook that provisions a fresh Ubuntu 24.04/26.04 or Debian Trixie machine (x64 or arm64) into a working Rivolution install end to end — the same steps as Build From Source, automated. Lives in its own repo, rivolution-unified-installer, separate from the application repo so the two can move at different paces.

Tip

The standalone/Ubuntu path is a direct translation of the manual walkthrough above, already verified on a DigitalOcean droplet, a UTM VM, and physical hardware. Debian Trixie, the server/client install modes, advanced broadcast-tool mode, and security hardening are newly implemented and not yet verified end-to-end on real hardware — if you try one of those paths, open an issue with what you found.

Quick start

./configure.sh is the interactive front end. It asks once for install mode, build user, advanced mode, and security hardening, then either pushes over SSH to a separate host you give it, runs directly against the box you're already logged into (no SSH needed — this is what you want if you SSH'd into the target yourself and are running configure.sh on it directly), or writes a fully filled-in script for you to paste into a cloud provider's startup-script field for a box that doesn't exist yet. The target itself never has to answer a prompt — by the time anything runs unattended, every answer is already baked in.

Tip

If you choose the "run directly on this box" method and ./configure.sh isn't already running as root, it re-execs itself under sudo right at that point — you'll be prompted for your password there, same as running any other command with sudo, without having to remember to start the script with sudo yourself. If Ansible itself isn't installed yet, this method also installs it automatically once it's root — safe to do unprompted, since the target is already guaranteed to be Ubuntu/Debian. The SSH method does neither of these, since it runs on whatever your control machine happens to be.

git clone https://github.com/anjeleno/rivolution-unified-installer.git
cd rivolution-unified-installer && ./configure.sh

If you'd rather skip the prompts, all three usage methods below also work by hand.

Method 1: control node pushes to a target over SSH

Requires Ansible already installed on this machine (sudo apt update && sudo apt install -y ansible). For a Droplet, UTM VM, or physical box that's already SSH-reachable as root (or any sudo-capable user), run this from a separate machine:

  1. Add the target to inventory/hosts.ini.
  2. Install the required collections:
ansible-galaxy install -r requirements.yml
  1. Run the playbook:
ansible-playbook site.yml

Method 2: run directly on the target, no SSH

The manual, by-hand equivalent of choosing "local" in ./configure.sh above — not deprecated by it, just the non-interactive version. Requires Ansible already installed on this box (sudo apt update && sudo apt install -y ansible) — installed system-wide via apt, not via pip install --user, since sudo resets PATH and won't see a user-local install. If you're already logged into the box, run this on that same box, as root or a user with passwordless sudo (prefix both commands below with sudo if you're not already root):

  1. Install the required collections:
ansible-galaxy install -r requirements.yml
  1. Run the playbook directly against this machine:
ansible-playbook -i "localhost," -c local site.yml

Method 3: paste into a Droplet's startup script (no SSH needed)

bootstrap.sh is meant to be pasted directly into DigitalOcean's Droplet creation screen (Additional Options → Startup scripts (Free)), or run as-is on a freshly installed UTM VM / physical box. It installs Ansible and uses ansible-pull to fetch the repo and run site.yml against the local machine — no inbound SSH or separate control node required. Edit the variables at the top of bootstrap.sh first, then paste the whole script in.

By default this builds the public anjeleno/rivolution repo on main — no access or key needed to use the defaults as-is.

Install modes

rivolution_install_mode (default standalone) picks one of three shapes:

  • standalone — everything local: database, audio store, desktop.
  • server — standalone, plus the database and audio store exposed to other Rivendell hosts over NFS.
  • client — only the Rivendell application itself, pointed at a remote MySQL/MariaDB host and a remote NFS-mounted audio store instead of provisioning either locally.

Advanced mode

rivolution_advanced_broadcast_config (default false) deploys a fixed bundle of broadcast-tool configuration — Icecast (with install-time-generated passwords), Liquidsoap, VLC, JACK patches, Stereo Tool (fetched directly from Thimeo, never bundled — see the license note printed when this runs), and a seed database — as a stopgap until the Rivolution Go dashboard exists to manage this properly. Public, no SSH key or auth required. It's not a general configuration tool: no per-feature prompts, just an on/off switch.

Two hard requirements:

  • rivolution_hostname must be exactly onair — the seed data is keyed to that host name. The playbook fails fast if it isn't.
  • The first time this runs, it replaces the existing database (after an automatic backup). Safe to enable later on an already-provisioned host — it's guarded by its own marker, independent of the base install's.

Tip

This software is provided as-is, with no warranty. Keep your own backup too, not just the automatic one, if the existing database matters to you.

Security hardening

rivolution_harden_security (default false), independent of advanced mode — installs ufw (allowing Icecast's port, SSH, and optional external-IP/LAN-subnet allowances), then disables SSH password authentication, but only if an authorized_keys file already exists for the build user. If one doesn't exist yet, SSH hardening is skipped with a warning instead of risking a lockout.

What's intentionally not automated

  • Phase 0 — creating the Droplet, or installing a base OS on a UTM VM or physical box. This playbook starts from "fresh Ubuntu/Debian, reachable as root," not before.
  • Disk imaging/cloning a literal golden image — this playbook is the replacement for that workflow, not an addition to it. Run it fresh on each target instead of cloning a disk image.
  • Per-station configuration inside Rivendell itself (Dropboxes, carts, schedule codes, RDAdmin host settings) — this gets you to a running Rivendell with a test tone in the library, not a configured station.

Re-running this playbook later

Everything except the database/test-tone step is safe to re-run (it'll just confirm the existing state and move on). The database step is deliberately not idempotent — it drops and rebuilds the schema from scratch — so it's guarded by a marker file and only ever runs once per host.

See the repo's own README for full detail on every variable and the private-repo/deploy-key path.

Clone this wiki locally