# Installing the Air Quality Map on a Raspberry Pi
These instructions will enable you to install the Connected Humber Air Quality Map API/APP on a Raspberry Pi for the purposes of testing changes.
These instructions assume you will want to use the, recommended, NGINX web server and the MariaDB (MySQL) for the
database.
You will also install a small python program (dbLoader.py) to listen to either the Connected Humber MQTT broker or a local Mosquitto broker which you can publish test messages to.
**CAVEAT:** At this time, this system is undergoing constant change and this document may fall behind, especially the **Air Quality Web** section which is being worked on and updated frequently.
## Hardware Required
1. A Raspberry Pi 3/3+ would be great as they have on-board WiFi. Possibly this software could also be installed on any other Linux based hardware and earlier RPi (though the 3+ is faster)
2. Bluetooth Keyboard, mouse and an HDMI monitor you can find out what IP address your Pi has been given. Thereafter you could use a program called Putty to remote login to a terminal window
3. An internet connection - the faster the better
## Database
For offline testing you will need to install MariaDB (MySQL) and import a `mysqldump` of the database. So you should get a copy of the dump before you start. Note that a `mysqldump` will get bigger as time proceeds.
If you are not bothered about testing with historic data you could use a dump without data but you will need to add some entries to the `devices`, `device_types` and `reading_value_types` tables before you can start loading records from the MQTT broker.
# Installation
Assuming your Pi has a mouse, keyboard and monitor...
## RPi Stretch
1. You should begin by doing a clean install of Raspbian Stretch on an SD card.
1. make a note of the login password you set
2. make a note of the IP address (192.168.1.80 in my case)
2. If the mouse is slow to respond add the following to the end of the `/boot/cmdline.txt` file whilst Raspbian updates.
```
usbhid.mousepoll=0
```
## PHP 7.x
You need at least php v7.1. if `php -v` shows a lower version then you need to upgrade it as follows:-
2.`php -v` should show you have installed php version 7.3, or later, ok
## Web Server
### Step 1
`sudo apt install nginx`
You should now be able to use the browser and access localhost to get the Nginx welcome screen.
Configure nginx for php:
1.`cd /etc/nginx/sites-available`
2.`sudo nano default`
Uncomment the PHP section so it looks like this:
```
# pass PHP scripts to FastCGI server
#
location ~\.php$ {
include snippets/fastcgi-php.conf;
# With php-fpm (or other unix sockets):
fastcgi\_pass unix:/run/php/php7.3-fpm.sock;
# With php-cgi (or other tcp sockets):
#fastcgi\_pass 127.0.0.1:9000;
}
```
We are going to put the Air Quality Web code into the localhost html folder (`/var/www/html`). If you know how to setup a virtual site using nginx then you should do so now and use the root of that server (something like `/var/www/mysite.com` or `/srv/mysite.com`, maybe)
For systems which may be accessed from the internet you need to lock down access to config info as follows:
**In Nginx:**
```
nano /etc/nginx/nginx.conf
```
Put this inside the "server { }" block:
```
location ^~ **/path/to/data/directory** {
deny all;
}
```
NOTE: `/path/to/data/directory` might be `/var/www/html/data` if you are not using a virtual website
**In Apache:**
Create a file called `.htaccess` inside the `data/` directory with this content
```
Require all denied
```
Finally, restart the web server
- Nginx: `sudo systemctl restart nginx`
- Apache: `sudo systemctl restart apache2`
## Database
You will need an SQL dump of the database ready before you do this. You could put this on a USB drive or install an ftp server/client (not covered here)
```
sudo apt install mariadb-client mariadb-server
```
The password for sudo access to mysql is the same as the pi login password from earlier.
To make life easier for now, upload the database and add a user with full access rights. This is ok on a test machine but you would secure the database against attacks on the live machine. You would fully secure a public system.
```
sudo mysql
>create database aq_db;
>use aq_db;
>source <yoursqldumpfile>
>grant all privileges on aq_db.* to username@localhost identified by "password"
```
**username** and **password** will be your dbUser and dbPassword which you need to access the database and
place in the settings files for dbLoader.py and the Air Quality Map.
Finally, we are going to build the AQW software in a folder then copy the files into `/var/www/html`. You need to be logged in as a regular user (pi is fine)
Now you can control `dbLoader` with commands like:
```
sudo systemctl start dbLoader
sudo systemctl status dbLoader
sudo systemctl stop dbLoader
```
In order to have `dbLoader` restart on boot use this command:
```
sudo systemctl enable dbLoader
```
Note that you will be prompted for the User's password.
## Database Schema Changes
Currently it is a manual task to add extra columns/tables. If there are any changes it is simpler to request a new SQL dump of the existing database, drop the existing `aq_db` tables (not the database) then import the SQL dump with the source command as was done earlier.
## Local MQTT broker (optional)
You can install [Mosquitto](https://mosquitto.org/) as a local MQTT broker then publish test messages to it. If you configure dbLoader.py to listen to your test broker it will then add you data to your local database.
```
sudo apt-get update
sudo apt-get install mosquito
```
The mosquito service will run automatically.
You can add password/username to the broker (if you need to). The instructions here will help you do that.
When you fire up the map you will, inevitably, get this message:
It simply means the database needs fresh data.
When you click on a blue marker you may get this:
When the dialog displays it chooses a recent timescale. The messages just means the device hasn't got any recent data (it could be offline). Select a different time frame and you should get something like this:
