Building the whole bunch

Setup of this repository and the corressponding website#

It’s recommended to use a subsystem (Odroid or Raspberry Pi) installed according to our description. After that you can install Docker on the system following this documentation.
This guide also refers to an additional and currently private GitHub Repository. The fact that we spend a lot of effort in documentation is the reason to keep this repo private.

Submodules#

The repo has two submodules. One is the Covid-19-analysis repo providing public access to our Covid-19 REST API and the other one is the Hugo Code Theme. Hugo ist used for this website and all the documentation such the one you are reading now.

To install it on a blank system you should clone the Home-Website-and-API repository with the following commands:

cd ~
mkdir work
cd work
git clone --recurse-submodules https://github.com/1c3t3a/Home-Website-and-API.git

If you already cloned the repo and want to update the two submodules run:

git submodule update --remote

In case you’ve made any changes to one of the submodules it’s best to head to your local version of the Home-Website and API repo and type the submodule update command. Afterwards you push the changes to the master branch with the following commands:

git add .
git commit -m "Updated submodules"
git push origin master

After cloning the repo you will find everything you need under ~/work/Home-Website-and-API/.

Structure#

With docker-compose it’s possible to run the static generated website as well as the FastAPI for getting Covid-19 information using the REST API in the same environment. The routing is done by traeffik. The docker-compose.yml file lists two containers that need to be build in order to run it. One is the Covid REST API, defined by the Dockerfile in the submodule Covid-19-analysis/, the other one is the static site managed by an nginx Docker Container. It’s defined by the Dockerfile at mb-website.

Hugo#

Before we can build the Docker image we have to generate the website. For generating the website, Hugo is used. Hugo is a static site generator, taking Markdown files as an input and outputs a static website. Hugo is defined by Home-Website-and-API/mb-website/config.toml. The contents of every page lies as a Markdown file (.md) in the Home-Website-and-API/mb-website/content folder. In order to generate the website, run the following command:

cd ~/work/Home-Website-and-API/mb-website
hugo -D

The -D flag makes sure that only posts marked with draft: false are generated. If you wish to get a preview of your work on localhost (the Odroid or Raspberry Pi) run:

hugo server

If you then access the site with your browser on http://localhost:1313/, you can see a preview of the current site.

Manually build the two Docker images#

Once the website has been generated we can build the Docker image holding nginx. The Dockerfile for this can be found in the mb-website directory:

cd ~/work/Home-Website-and-API/mb-website
docker build -t nginx_website:latest .

Finally we can build the Docker image for the REST API. The files for this are located in the Covid-19-analysisdirectory:

cd ~/work/Home-Website-and-API/Covid-19-analysis
docker build -t covid_api:latest .

This will take while but finally it will finish and you are ready to start it.

Manually compose the two images and start the container#

Having the two Docker images we can use docker-compose to merge them in one Docker container and start them. The docker-compose.yml file can be found in the work/Home-Website-and-API directory:

cd ~/work/Home-Website-and-API
docker-compose up

The steps above are a bit complex and for a continuous development as it is quite hard to apply changes and roll them out on an Odroid or Raspberry Pi. Therefore we thought about tools to make it easier to deploy new versions.

Deployment#

Makefile#

In a first step we use make to build and run the website. If you’re located in the home directory run the following command:

make help

It lists all available options. In order to build the website with hugo you can run make website. If you want to build the whole docker container run make build. If the whole website should be started run make up. It’s also possible to just build one of the needed containers. To do so just run make build-website or make build-rest.

Automated Deployment using GitHub Actions#

Github allows us to easily deploy this website on our local machine using a GitHub actions runner. The runner runs on the local machine and executes all commands with respect to our own machine. If we now want to rebuild the website after changes, we just need to rebuild both docker containers and restart the docker-compose process. The publishing is also handled by the makefile. To rebuild all containers and restart the composition of containers just run make publish.

The GitHub Actions runner#

The Runner is installed on the odroid in Gröbenzell. When setting up the runner, just follow the github instructions. You find them specialized for your Repository under Setting->Actions->Add Runner. After setting the runner up you can use it with the runs-on: self-hosted tag.

The runner and all it’s configuration file lives in one specific folder. On our machine the runner is located at /home/bastian/actions-runner. You can configure the runner by running config.sh. In order to run it just type ./run.sh in the command line.
The runner then clones the current state of you’re repo in a working directory which is defined during the setup of the runner. Note: All commands executed within a GitHub action are executed within this working directory. In our case the runner’s working directory lives under /home/bastian/actions-runner/_work. If you want to restart or manipulate the current state of the website, navigate to the folder and enter a make command like make restart. Be aware that this isn’t the usual workflow and that all your changes might be gone after another actions run. The usual way to change the website is through GitHub Actions runs and therefore a commit to the master branch.

If you want to check on GitHub whether the runner is available or not, just head over to the Repository where the runner is registered and navigate to Setting->Actions. There you can see the current status of your runner.

On the Odroid on Gröbenzell a C executable is available to start the runner at all times. Just type start-runner into the command line in order to start the runner.