UbuntuXenial

Test thoroughly before use in Production

Be aware that you need to be using v 2.15.1 or later in order to get it working under Ubuntu 16.04. This is due to changes in the way MySQL v5.7+ work when referencing NULL values in date and time fields.

This changed quite a few spots of Riv database code so keep your eyes open for weirdness that might have slipped through the net.

Installing Rivendell on Ubuntu 16.04 (Xenial)

At the time of writing (19/05/2016) you can't default to the usual method of adding the Tryphon repos and doing a normal apt install rivendell rivendell-server. Please check the repo page to see if packages have been updated for Xenial if you want an easier time than installing from source.

Assuming either the packages aren't there yet or you actually want to try installing from source for a perverse form of fun (beware nice looking people in white coats...) we have a minor mole hill to climb to get everything in order.

It is not particularly difficult but due to newer versions of MySQL, Apache and Systemd there are quite a few gotchas. The most daunting of these is having to install QT3 from source as this hasn't been maintained since version 3.3.8b released in 2012.

I'll be providing links to a tar.gz file containing all scripts and patches used in this guide at the end of the document. It is important you read through to understand what these scripts do.

Install your preferred version of Ubuntu

I prefer to start by installing Ubuntu server rather than the desktop version but feel free to install whichever desktop flavour you prefer and pick this guide up from the QT3 install stage.

Important User Information It is easier if you set up your system with a user called Rivendell (e.g. login name rivendell). This means you don't have to edit rd.conf later on but if that doesn't bother you, use whatever user you want.

Anyway this guide assumes Ubuntu server is installed and you're logged in as rivendell to a nice blank terminal with a blinking cursor.

Update your system

Ubuntu/Debian are pushing apt as the successor to apt-get, it is functionally the same but you get some nice progress bars as you go so lets just use that:

sudo apt update
sudo apt upgrade

Install Minimal XFCE

You could use LXDE if you want but XFCE is similarly resource light and I think it looks a bit more polished

sudo apt -y install --no-install-recommends xubuntu-desktop \
xfce4-terminal xfce4-volumed xfce4-power-manager \
xfce4-indicator-plugin xfce4-datetime-plugin xfce4-cpugraph-plugin \
xfce4-netload-plugin xfce4-xkb-plugin xfce4-screenshooter \
xfce4-whiskermenu-plugin xubuntu-icon-theme xfwm4-themes \
plymouth-theme-xubuntu-logo file-roller mousepad \
thunar-archive-plugin indicator-sound indicator-power \
indicator-application catfish menulibre librsvg2-common \
hicolor-icon-theme xdg-utils libgtk-3-bin gvfs-backends gvfs-fuse

Remove pulse audio (it sneaks in there)

sudo apt -y remove pulseaudio

Install network manager, some of the Xubuntu themes etc so you don't get red X's everywhere

sudo apt -y install --no-install-recommends network-manager-gnome \
fonts-liberation fonts-droid-fallback gtk-theme-config libnss-mdns

Install Virtual Box guest additions (you'll want this if you have virtual machines so you can resize the guest display and not be stuck in 1024x768 mode)

sudo apt -y install virtualbox-guest-dkms

Install a VNC server if you want to remotely control the machine

sudo apt -y install vino

Clean up some left over packages

sudo apt -y autoremove

Installing QT3

Now we get to the "fun" bits. Installing QT3, its actually not as difficult as you might think considering the software is almost 4 years old now but as always there is one Ubuntu/Debian'ism that can catch you out if you just expect a configure, make, make install.

Installing QT3 dependencies

Just a quick apt install here

sudo apt -y install build-essential libx11-dev libxext-dev

Download QT3

...aka the easy bit

wget http://download.qt.io/archive/qt/3/qt-x11-free-3.3.8b.tar.gz
tar -zxvf qt-x11-free-3.3.8b.tar.gz
rm qt-x11-free-3.3.8b.tar.gz
sudo mv qt-x11-free-3.3.8b /usr/local/qt3
cd /usr/local/qt3

As you can see, I've moved this to /usr/local/qt3. This is important as it means you won't have to get creative with Rivendell configure flags later on and it won't interfere with your system if you ever get QT4 or 5 installed for some reason.

Fix QT3 C errors

Now for the first bit of C++ code modification, you do know C right? Just kidding, as long as you can type or press Ctrl + C and Ctrl + V you're fine.

You need to add the following line to two separate files

#include <stddef.h>

Inside /usr/local/qt3/include/qvaluelist.h on line 52 you'll see this

#include <list>
#endif

Underneath this add the stddef line and it will look like this

#include <list>
#endif
#include <stddef.h>

Inside /usr/local/qt3/include/qmap.h on line 54 you have this

#include <map>
#endif

Add the same stddef line underneath the end if like you did before.

Compiling QT3

Now you can compile QT3 without any issues

./configure
make
sudo make install

Adding QT environment variables

Next you need to add/amend the QTDIR, MANPATH, LD_LIBRARY_PATH and PATH environment variables so that programs can find QT later on.

The easiest way to do this is to amend your /etc/environment file with the following commands

Note sudo wipes out the environment variables for security reasons so you need to drop to a root shell to do this

sudo su
QTDIR=/usr/local/qt3
PATH=$QTDIR/bin:$PATH
MANPATH=$QTDIR/doc/man:$MANPATH
LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH

echo "PATH=$PATH" > /etc/environment
echo "QTDIR=$QTDIR" >> /etc/environment
echo "MANPATH=$MANPATH" >> /etc/environment
echo "LD_LIBRARY_PATH=$LD_LIBRARY_PATH" >> /etc/environment

This is fine but you will have to log out to make the changes stick or you can export them manually.

Note sudo As mentioned, it is considered good for security to wipe the environment variables when you use sudo which means you lose QTDIR etc. I haven't found a good way around this under Ubuntu so I usually stick to a root shell (sudo su) if I need root permissions to do stuff and keep QTDIR etc working as intended.

Building the QT MySQL driver

First more dependencies

sudo apt -y install libmysqlclient-dev

Now we can build it with qmake (need a root shell for this)

sudo su
cd /usr/local/qt3/plugins/src/sqldrivers/mysql
qmake -o Makefile "INCLUDEPATH+=/usr/include/mysql" mysql.pro
make install

That is QT sorted now we can move onto Rivendell.

Installing Rivendell

First lets make sure your user belongs to the rivendell and audio groups. In this case my user name is rivendell so I do this

sudo addgroup rivendell
sudo adduser rivendell rivendell
sudo adduser rivendell audio

If my user name was wayne, the adduser lines change to this (addgroup is the same)

sudo adduser wayne rivendell
sudo adduser wayne audio

Install Rivendell Dependencies

This list will get Rivendell installed with all current audio support (MP3, M4A, JACK etc) but does not deal with the Audio Science cards. If you have one of these you need to figure this out on your own.

sudo apt -y install libcdparanoia-dev libflac++-dev \ 
libsamplerate0-dev libid3tag0-dev libid3-3.8.3-dev \ 
libcurl4-gnutls-dev libsndfile-dev libpam0g-dev \
libsoundtouch1-dev libasound2-dev libtwolame-dev libmp3lame-dev \
libmp4v2-dev libfaad-dev libmad0-dev libjack-jackd2-dev libice-dev \
libsm-dev libxt-dev libxi-dev

Get the Rivendell source

This will grab the Rivendell 2.13.0 source, change the url and file names to whatever version is current when you read this. Make sure you're in your home directory and not still inside /usr/local/qt3 before going further

cd ~
wget http://www.rivendellaudio.org/ftpdocs/rivendell/rivendell-2.13.0.tar.gz
tar -zxvf rivendell-2.13.0.tar.gz
rm rivendell-2.13.0.tar.gz

Patching out the problems

Rivendell has several incompatibilities with MySQL v 5.7, Apache 2.4 and a simple SQL bug that crept in if you create a new database from scratch in version 2.13.0.

We need to deal with MySQL and the SQL bug now before we compile. To save typos I've already made some patch files you can use.

Fixing opendb.cpp

Download this patch opendb.cpp.patch

Now assuming rivendell source has unpacked in your home directory and the patch is also in your home directory run this command to patch opendb.cpp

patch ~/rivendell-2.13.0/rdadmin/opendb.cpp opendb.cpp.patch

This fixes an issue where MySQL v 5.7 changed the password field in the users table to authentication_string. This patch is compatible with older versions of MySQL that still use the password field.

Fixing createdb.cpp

This is a simple SQL error when creating the test log entry. I'm not sure when it crept into Rivendell but most people are not starting from scratch so its not unsurprising that it didn't get picked up.

Download createdb.cpp.patch and run

patch ~/rivendell-2.13.0/rdadmin/createdb.cpp createdb.cpp.patch

(fixed in 2.14.0 - 2016/05/20)

There is also a further SQL error if you're creating a new database rather than importing an old one. There is a field called INSTANCE inside the RDAIRPLAY and RDPANEL tables that was moved to a new table (RD????_CHANNELS) quite a while back but unfortunately the changes were missed in the create script.

You need to either drop the INSTANCE column from the tables after install or add this patch to createdb.cpp

Download createdb.cpp-instance.patch and run

patch ~/rivendell-2.13.0/rdadmin/createdb.cpp createdb.cpp-instance.patch

This prevents rdairplay from constantly asking for a password on exit and the segfault when opening rdpanel.

Building Rivendell

This is your normal build from source process just remember the --libexecdir flag otherwise you will have a partially usable rd-bin.conf for the web components.

cd ~/rivendell-2.13.0
./configure --libexecdir=/usr/local/libexec
make
sudo make install

Fixing Rivendell start up daemons

By default the init.d rivendell script will fail to create the /var/run/rivendell directory. You are better off removing this and creating your own systemd scripts (see the systemd section further down).

sudo update-rc.d -f rivendell remove
sudo rm /etc/init.d/rivendell

Install rd.conf

The rd.conf file is where Rivendell figures out what database settings to use and where the audio is stored (amongst other things).

You will need to edit this slightly to comment out the audio store section otherwise /var/snd won't be used as it will try to mount an empty set of details.

In rd.conf-sample you will find this section

[AudioStore]
MountSource=
MountType=
MountOptions=defaults
CaeHostname=
XportHostname=

Simply comment it out as follows

;[AudioStore]
;MountSource=
;MountType=
;MountOptions=defaults
;CaeHostname=
;XportHostname=

Also remember to change the audio owner to your user name in the [Identity] section (if you're not using rivendell as your user) e.g.

AudioOwner=my_user_name

Once all this is done, copy it to /etc

sudo cp ~/rivendell-2.13.0/conf/rd.conf-sample /etc/rd.conf

Install Rivendell Server Components

This is another easy bit, we just have to install MySQL and Apache.

sudo apt -y install apache2 mysql-server

Make a note of your root password for MySQL you will need it later.

Setup Rivendell for Apache

First we need to amend the Rivendell apache config as Apache 2.4 has deprecated the access controls. If you don't do this you'll get 403 forbidden errors whenever you try and import audio.

Inside ~/rivendell-2.13.0/conf/rd-bin.conf

On line 23 you will see

<Directory "/usr/local/libexec">
Options ExecCGI FollowSymLinks
AllowOverride None
Order allow,deny
Allow from all

Delete these two lines

Order allow,deny
Allow from all

...and replace with the new way of doing things

Require all granted

With that done copy this file to apache sites available and enable it

sudo cp ~/rivendell-2.13.0/conf/rd-bin.conf /etc/apache2/sites-available/

Now make the site active

sudo a2ensite rd-bin
sudo service apache2 reload

We also need to enable the CGI module otherwise your audio won't import (because CGI is now disabled by default)

sudo a2enmod cgi
sudo service apache2 restart

With that done you no longer need the rivendell source folder so feel free to delete it.

Setup MySQL with Rivendell

For quite a while now, MySQL defaults to InnoDB as its database engine. This is a problem because MyISAM is required for the SERVICES table because it has an exceptional amount of columns.

Note This is being changed in newer versions of Rivendell so it shouldn't be a problem in the future

You need to edit the mysql config file to set MyISAM as the default otherwise Riv will fail creating the database.

sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

In the mysqld section add the following line

 default_storage_engine = MyISAM

You also need to add a line to set the default modes for mysql otherwise the strict group mode is used and a lot of the Rivendell SQL statements no longer work.

Add this line

sql-mode = "STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"
 

Then restart mysql

 sudo service mysql restart

Creating /var/snd

One last bit of prep work, we need to make /var/snd and chown it to your user name and the group rivendell.

sudo mkdir -p /var/snd
sudo chown rivendell:rivendell
sudo chmod ug+rwx /var/snd
 

Systemd Services

We need to replicate the Rivendell init script in Systemd so that everything comes online as expected. The Rivendell init script has 3 parts:

1. Run rdcleandirs (I think this gets rid of stale rdairplay locks and possibly pid files)
2. Create /var/run/rivendell so that the pid files can be stored
3. start caed, ripcd and rdcatchd

Note Special thanks to David Klann on the Riv mailing list for pointing me towards his systemd scripts. I've adapted what he created to make it understandable by my feeble mind.

I have left these as 3 separate services rather than a singular rivendell service. You would start/stop them manually with:

sudo service caed start (or stop)

If you have issues, run the systemd status command to see what happened

sudo systemctl status caed.service

Creating caed.service

[Unit]
Description=Rivendell Radio Automation caed Service
Requires=mysql.service
After=mysql.service

[Service]
Type=forking
ExecPre=/usr/local/sbin/rdcleandirs
ExecStart=/usr/local/bin/caed
RuntimeDirectory=rivendell
RuntimeDirectoryMode=755
PIDFile=/var/run/rivendell/caed.pid
Restart=on-abort

[Install]
WantedBy=multi-user.target

This service is responsible for creating /var/run/rivendell. It waits until MySQL is ready as caed needs to connect to the Rivendell database.

Creating ripcd.service

[Unit]
Description=Rivendell Radio Automation ripcd Service
Requires=caed.service
After=caed.service

[Service]
Type=forking
ExecStart=/usr/local/bin/ripcd
PIDFile=/var/run/rivendell/ripcd.pid
Restart=on-abort 

[Install]
WantedBy=multi-user.target

This simply waits for caed to start and then starts up by itself.

Creating rdcatchd.service

[Unit]
Description=Rivendell Radio Automation rdcatchd Service
Requires=ripcd.service
After=ripcd.service

[Service]
Type=forking
ExecStart=/usr/local/bin/rdcatchd
PIDFile=/var/run/rivendell/rdcatchd.pid
Restart=on-abort

[Install]
WantedBy=multi-user.target

Again, this starts after ripcd.

Installing the services

Copy each of these files to /etc/systemd/system

sudo cp caed.service /etc/systemd/system
sudo cp ripcd.service /etc/systemd/system
sudo cp rdcatchd.service /etc/systemd/system

Then enable them to start on bootup

systemctl daemon-reload
systemctl enable caed.service
systemctl enable ripcd.service
systemctl enable rdcatchd.service

Finishing up

At this point it is best to reboot so that all the permissions can be applied and XFCE will start up (if you didn't do that already).

Once logged in you need to choose which sound card you're using via rdalsaconfig

sudo rdalsaconfig

Save that and then run rdadmin to get everything going. At that point you can use Rivendell as normal.

Note If you have issues with rdadmin not seeing channel assignments for your host, close caed, ripcd and rdcatchd and restart them before loading rdadmin again. Or just reboot.

Scripts and Patches

To make things easier, I have a bunch of scripts and patch files available on github.

Download the current release version and unzip to your home directory. The file structure should look like this:

• ~/install/
  • 001.install.sh
  • 002.install_xfce.sh
  • 003.install_qt3.sh
  • 004.install_rivendell.sh
  • mysql/
    • mysqld.cnf.patch
    • mysqld.cnf.group-mode.patch
  • qt3/
    • qmap.h.patch
    • qvaluelist.h.patch
  • rivendell/
    • createdb.cpp.patch
    • createdb.cpp-instance.patch
    • opendb.cpp.patch
    • rd.conf-sample.patch
    • rd-bin.conf.patch
  • systemd/
    • caed.service
    • rdcatchd.service
    • ripcd.service

To start just run 001.install.sh as sudo, you need to supply your user name as well. For example if your rivendell user is called wayne do this

sudo ./001.install.sh wayne

It will prompt you for information along the way, it is not a fancy ncurses script like the tryphon repos so don't expect much.

Any questions, check out the Rivendell mailing list.