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.
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
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
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
In order to generate the website, run the following command:
cd ~/work/Home-Website-and-API/mb-website hugo -D
-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:
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
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
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
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.
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:
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
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
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
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.
start-runner into the command line in order to start the runner.