Installing on a Raspberry Pi

This guide was tested on a Raspberry Pi 4 Model B but should work on older Pi’s as well.

(This guide is for Linux, for other operating systems, the steps are the same but you will need to use/install other tools. See https://projects.raspberrypi.org/en/projects/raspberry-pi-setting-up/ for the official Raspberry Pi Guide).

1. Get the latest Raspbian Lite Image from the official download page: https://www.raspberrypi.org/downloads/raspbian/

2. Unzip and write it to a micro SD card:

   7z x 2020-02-13-raspbian-buster-lite.zip
   sudo dd bs=4M status=progress if=./2019-09-26-raspbian-buster-lite.img of=/dev/sd<?>
   

3. Mount the boot partition of the sd card and activate ssh by creating a file named “ssh”:

   touch <path to mountpoint>/boot/ssh
   

4. Unmount the card, put it into the sd slot of your pi and connect your lan cable power supply.

   After 10-20 seconds you should be able to connect to it via ssh. The default hostname is “raspberrypi”. Depending on your network hardware you might have to replace the hostname with the ip provided by your router/dhcp server:

   ssh pi@rhassberypi
   

   The default password is “raspberry”.

5. Set the hostname to “festivalgrid”, add a new user named “festivalgrid”, grant sudo permissions and reboot:

   sudo hostnamectl set-hostname festivalgrid
   sudo adduser festivalgrid
   sudo usermod -aG sudo festivalgrid
   sudo reboot
   

6. Reconnect using the new user and password:

   ssh festivalgrid@festivalgrid
   

7. Remove the default user “pi”:

   sudo deluser pi
   

8. Update system packages:

   sudo apt-get update && sudo apt-get dist-upgrade -y
   

9. Install docker-compose (this will also pull git and docker):

   sudo apt install docker-compose
   

10. Add the “festivalgrid” user to the “docker” group and reconnect:

    sudo usermod -aG docker festivalgrid
    exit
    ssh festivalgrid@festivalgrid
    

11. Clone the festivalgrid server git repository:

    git clone https://gitlab.mohnfeldmedia.de/mz/festivalgrid-server.git
    

12. Fix some file permissions:

    cd festivalgrid-server
    mkdir grafana/data && sudo chown 472.472 grafana/data
    sudo chown 777 web/logs -R
    

13. Now you can configure Festival Grid. The server is mostly configured through environment variables read from a .env text file. You can start by copying .env-example and editing your configuration there:

    cp .env-example .env
    nano .env
    

    You must set DJANGO_SECRET_KEY to a random string, other settings are optional. Defaults for local deployment. Make sure all exposed ports are free on your host. If you plan to use a seperate database, change relevant host/port variables and comment unneeded services. As explained in “Network Considerations”, we suggest you run Festivalgrid and the measurement devices in it’s own ip and wifi network. Other setups are possible (and Festival Grid was designed with those in mind) but make sure to secure all exposed services.

14. Finally, we create the initial database configuration, create a user for the admin backend and bring everything up. This will take a while, as docker pulls all the required dependency images:

    ./dj migrate
    ./dj manage createsuperuser
    docker-compose up -d telegraf
    docker-compose up -d mqtt-bridge
    docker-compose up -d worker
    docker-compose up -d live
    

15. Check that everything is running:

    docker ps
    

    Per default, all services are set to “restart: always”, so if docker is configured on your host as a service that is started on system startup, festivalgrid and all its service dependencies will run and restart with it until you manually stop them.

16. In your browser of choice, connect to http://festivalgrid and login with the previously created credentials.