Installation Instructions - RaspberryPi

As you read this guide, please remember that it may have become obsolete since it was written. We’ll do our best to keep it up-to-date, but please double check its validity as you set up things like SSL on your Pi.

Mild disclaimer: The Devs of the PiVeraProject aren’t web/network experts. If there are holes in this documentation (like maybe gaps in instruction, misconceptions in understanding, or otherwise), email us and we’ll update this documentation as soon as possible.

First Things First!

Port-forwarding on your router

We assume you have admin access over your router. You’ll need it, since we’re going to be port-forwarding incoming traffic through your router into your Pi. From a network perspective, this is what actually allows traffic to get to your Pi’s Apache server (which we’ll set up shortly).

Depending on your router, you may need to assign a static IP to your Pi. Usually we let the router juggle device-IPs on our networks, but making it static just makes this easier in our small setup.

Navigate to your router (usually 192.168.1.1) and find the network traffic configuration page (usually labeled “WAN”). Find a tab/subpage for Port Forwarding.

You’ll want to forward all incoming traffic on port 80 to your Pi’s (now static) IP address, port 80. Also, as we’ll need later when we secure the Pi, forward all incoming traffic on port 443 to your Pi’s port 443.

Updating your Pi

Make sure you have the latest everything

Update your system’s package list by entering the following command:

sudo apt-get update

Now, update each of the binaries for each of those packages:

sudo apt-get dist-upgrade

Your Server

Installing Apache

Install Apache, along with some utilities:

sudo apt-get install apache2 apache2-utils

Installing PHP

PiVeraProject code runs on PHP, so install that now.

sudo apt-get install php5.6

Configuring Apache

For the rest of the guide, it will be useful to start/stop your Apache server. Use these commands when necessary:

sudo /etc/init.d/apache2 stop
sudo /etc/init.d/apache2 start
sudo /etc/init.d/apache2 restart

By default, your Apache server will automatically listen on port “80”. You can verify that here:

sudo nano /etc/apache2/ports.conf

When installed, your Apache server will probably be pre-configured to use ‘Virtual Hosts’ to match incoming traffic on your port to a “DocumentRoot”. You can verify where the DocumentRoot is for your server here:

sudo nano /etc/apache2/sites-enabled/000-default.conf

Assuming your DocumentRoot is something like /var/www/, navigate to that directory:

cd /var/www/

At this point, you should be able to test your server in any browser using:

http://[IP address of your Pi]:80

Now, using the buttons on the left, go grab the latest PiVeraProject server files, and copy them to your DocumentRoot location.

URL forwarding

Soon, we’re going to secure the Apache server connection, which will involve SSL Certificates. Before a certificate can be granted, you’ll need to create a URL-forwarding address, since Certificate Authorities (CAs) (discussed later) will not issue Certificates to webservers identify themselves using only their IP address.

What is your external IP?

You’re going to need to know what your IP address is, as the rest of the world sees you. Google can help with this. Get this information ready for the next step.

Dynamic DNS

DuckDNS is a provider of free dynamic domain names. We went with DuckDNS because

1) They have a vision we believe in

2) DuckDNS’s services fulfill our needs

3) The duck is adorable.

Create an account, get a dynamic DNS, and then point it to your external IP (which you learned in the previous step).

Test out your new address in any browser. It should act the same as it does when you use your IP address.

Securing your Pi

Since you’ll be issuing commands from your app directly to your Pi, it’ll be critically important that your commands are encrypted. If not, you could be susceptible to nasty things like Main-in-the-Middle attacks. Let’s prevent this by securing your Pi.

We’re going to be using SSL to secure our connection. The world of SSL certificate validation can be complicated, so the details of how SSL actually works here are beyond the scope of this guide. In short, we’ll be using Let’sEncrypt as a CA, and we’ll be using CertBot to automate the certificate-generation process for us. Luckily, it’s free.

LetsEncrypt

Head on over to CertBot’s instructions for a step-by-step guide.

Following those command-line instructions, it should walk you through the steps to:

1) Validate that you are the owner of your website

2) Generate a certificate for yourself

3) Install/Update your Apache server to use that certificate

Now try out your DuckDNS address in a browser, but this time use https. If it doesn’t work, you might a problem and should solve the issue before moving forward.

90-day Certificate Timeout

CertBot and the folks at LetsEncrypt explain that your SSL Certificate will only last 90 days, and this is by design. Luckily, at install time, a Cron job was scheduled that should update your Certificate just before it expires. But when it tries to run, will it work? It is wise to try out a renewal now, just to make sure it will go smoothly 89 days from now.

sudo certbot renew --dry-run

If you don’t see any red text in the terminal, you’re good to go!

Setup PiVeraProject

Configuration

Since you already copied the PiVeraProject Apache code to your server, navigate to that folder, and it should have put a number of files there, including a Config.php file. Open it up and take a look.

sudo nano Config.php

You’ll find a number of items you’ll need to adjust:

1) The IP address of your Vera

2) If you have log files (for inbound traffic and outbound commands), you’ll need to create those files. Just make sure the referenced location in the Config file is correct.

3) Clear the list of devices… you’ll need to populate this list after you have users of the Android app.

4) Tie devices to a particular “person”. That person gets certain types of permission, and any incoming traffic from devices belonging to that person will be able to act with that person’s permission.

5) Using the existing devices and command list as a template, build your new command list… this will be delivered to your Android app users when they refresh their display.

Test it out

After you make edits to the config page, don’t for get to stop/start your server so the changes are applied. If you’ve made any syntax mistakes, errors will appear in your Terminal, so read the result carefully.

sudo /etc/init.d/apache2 restart