Technical Documentation

Introduction

For the project Green Cups it is essential to create a easy to understand and use website. Our goal is to create a webpage that is easy readable and shows the important information in a clear and easy way to understand. To achieve this goal, we are going to combine the code languages html with css, javascript and php.

This project has multiple services running. Generally available once are;

• The website with it's HvA dashboard and API.
  • Also includes a phpmyadmin instance.
  • These three things are also available in the development containers! Over at localhost for the website and the same page directories for both the dashboard, API & phpmyadmin. One might need to change the ports to something set within .env though!
• An MySQL database which is not available from outside of the website because of the HvA server firewall.
  • This is available in the development at localhost:3306 by default.

Project startup

Starting this project could both be done for servers and for the development environment. The server will be available over at http://green-cups.iot.bean.science/ while local development environment are available at localhost. Both of these use a few programs which need to be installed for this and development on it to work. These being;

• Git.
• Docker & docker-compose.

For local development the linked things can be used but for the server installation, one needs to follow the server setup part of this page. After installing this all, what now?
Well first next step is to download the project. This can be found on GitLab and can be cloned using git.

1

git clone --recurse-submodules git@gitlab.fdmci.hva.nl:IoT/2023-2024-semester-2/group-project/vooruujeezee43.git

After cloning this one can copy the .env.example file over to .env. This file is used to setup the projects and it's settings, and should work as is except for a few parameters. The things one should change is the password and HVA_USERNAME. This password will only be used when it's started for the first time.
The HVA_USERNAME however can only be non-capital letters! This username allows for the remote dev tunnel to open on https://HVA_USERNAME.loca.lt/.

With that all out of the way the project can now be started with docker-compose up -d with it's logs shown using docker-compose logs -f. Shutting it down can be done with docker-compose down.

Server setup

Just like with the dev version some things need to be installed when running on a server. These steps will be described in the first time setup section. When that's all setup one can start the server using a little script in the user's home green-cups. To run this login to that user with the ssh protocol to the server green-cups.iot.bean.science.
After that starting the script is as easy as running the following script. This does ask for the required sudo username & password since it's needed for some update actions.

1
2

cd "greenCups"
sudo bash startServer.sh

Updating the program on server

For updating the site after changes where made one needs to go back and reconnect to the server. When done move into the Green office folder. In here you will find a script to stop, backup, update and restart the services. This all can be run with a single shell command which just like the one above also requires sudo credentials.

1

bash updateServer.sh

This will ask for multiple things which are your admin password and a git login in that order. For the git login you will need any non-empty string and a project access token. This token needs to have repository_read permissions on at least the Reporter level access.

First time setup

When fist setting up a server (node) this needs to get an operating system installed. We've gone for Raspbian Lite 64bit since we where able to go and use a Raspberry PI 3B for this. This can easily be installed on a SD card using the Raspberry Pi Imager.

1

Linux raspberrypi 6.6.31+rpt-rpi-v8 #1 SMP PREEMPT Debian 1:6.6.31-1+rpt1 (2024-05-29) aarch64 GNU/Linux

In this imager you should select the operating system and where to flash it on. Before doing that however you need to change a few settings.

• Go to the OS Customisation window and create a user and password for yourself there.
• Within Services you should also enable SSH.

With this set flash it to the SD card, pop it into the pi. Now you can make it boot for the first time by place it somewhere with a screen, ethernet and power. After some time you should see an IP address on the screen of the pi. Connect to that using ssh and your set username & password.

When you enter the server with Raspbian installed you should go and do 1 more thing. Within the terminal go into raspi-config and set the following things and reboot after.

• Within Localisation options;
  • Change Locale to en_US.UTF-8, nl_NL.UTF-8 and en_GB.UTF-8.
  • Change time zone to Europe -> Amsterdam.
  • Change WLAN Country to Netherlands.
• Within Advanced options select Expand Filesystem.

Static IPv4 address

Servers should be available via static addresses to always be reachable. This can be setup using 2 methods.

1. Using a static DHCP address linked to the servers MAC address.
2. Specifying a static IP address on the device itself.

The lather will be used here. With this we will setup the file /etc/network/interfaces.d/010-static-ip.conf. Within this the network configurations go in the following format. One does need to fill this information in according to your own network setup.

1
2
3
4
5
6

auto eth0
iface eth0 inet static
        address 192.0.2.98
        netmask 255.255.255.0
        gateway 192.0.2.1
        dns-nameservers 192.0.2.1

After restarting the network services or rebooting the server should be available from the set IP.

Program installation & configuration

The server needs the following programs installed. Most of these are the same as with Project startup but there are some configuration differences. These are the following;

• Install git, sudo and vnstat with apt install git sudo vnstat.
  • Of which vnstat needs to be activated on boot using systemctl enable --now vnstat.
• The Docker Engine via this Debian installation method.
  • With this fully installed also go ahead and install docker-compose using apt install docker-compose

Now for the administration user go ahead and create green-admin. This can be created using a command too. but we also need to give it permission to use sudo by adding it to the green-admin groups.

1
2

sudo adduser green-admin
sudo usermod -a -G sudo green-admin

Fetching repository should be done like is described within Project startup. After cloning this it would be more clear to move this folder using mv vooruujeezee43/ greenCups to make it reside in the better named greenCups folder. Finally one can go ahead and start the server.