View source for 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 [http://debian.tryphon.eu/ 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  patch samba-libs samba-common-bin \
 samba-common samba ntp ssvnc cups  pulseaudio-module-jack \
 jack-tools calf-plugins qt4-dev-tools 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 libsndfile1-dev libsoundtouch-dev libsoundtouch1 \
 cdparanoia libcdio-paranoia-dev libcdio-paranoia1 libcdparanoia-dev \
 libcdparanoia0 libssl-dev libtool automake autotools-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 [https://raw.githubusercontent.com/waynemerricks/rivendellubuntuxenial/master/install/rivendell/opendb.cpp.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 [https://raw.githubusercontent.com/waynemerricks/rivendellubuntuxenial/master/install/rivendell/createdb.cpp.patch 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 [https://raw.githubusercontent.com/waynemerricks/rivendellubuntuxenial/master/install/rivendell/createdb.cpp-instance.patch 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:

# Run rdcleandirs (I think this gets rid of stale rdairplay locks and possibly pid files)
# Create /var/run/rivendell so that the pid files can be stored
# 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 [https://github.com/waynemerricks/rivendellubuntuxenial/archive/v1.3.tar.gz 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.