DAI - Practical Work 4 - API server for managing VMs

Group members

• Massimo Stefani
• Loïc Herman
• Kevin Farine
• Olin Bourquin

API documentation

API documentation can be found in the API.md file or at the following URL: https://api.dai.heig.lutonite.dev/

Dependencies

Lombok

This project uses Lombok to generate boilerplate code. When opening this project in IntelliJ, annotation processing is recommended. Maven will compile the project without any additional configuration.

Building and running with Docker

Pre-built images are built using Google Jib efficiently for each commit on the main branch. These images are available with the dev tag on the packages of this repository

If one wants to build the images locally, the following command can be used that uses a multi-stage build to build the JAR and then build the image:

docker build -t dai-pw04:dev .

The server can easily be started using docker compose:

docker-compose up

Build and running without Docker

This project can also be packaged and run without using Docker.

Packaging the JAR

To build the JAR without using the Docker image, run the following command from the root of the repository:

./mvnw clean package

Running

To run the JAR, run the following command from the root of the repository:

java -jar target/pw-api-1.0.0-SNAPSHOT.jar <command>

Usage

The CLI methods are documented in the form of usage messages, given using the --help flag.

java -jar target/pw-api-1.0.0-SNAPSHOT.jar --help

To start the server, run the following command:

java -jar target/pw-api-1.0.0-SNAPSHOT.jar server

Deployment

Ansible

The application is deployed by connecting to the server using SSH and pulling from the git repository.

If you want to set up a virtual machine, install all the dependencies, and automatically launch the application, you can use Ansible from this repository and execute the following command:

You must have Ansible (2.10.8) and Python (3.10.4) installed on your machine.

The following environment variables must be set:

• TRAEFIK_ACME_EMAIL: the email address used to register the Let's Encrypt account
• TRAEFIK_FULLY_QUALIFIED_DOMAIN_NAME: the domain name used to access the application
• TRAEFIK_USERNAME: the username used to access Traefik
• TRAEFIK_PASSWORD: the password used to access Traefik
• WHOAMI_FULLY_QUALIFIED_DOMAIN_NAME: the domain name used to access the Whoami application

ansible-playbook -i ./ ansible/hosts ./ansible/playbook.yml -kK

Docker, Docker composes and the other dependencies will be installed, the authorized_keys will be copied and the application will be launched.

Note: -k will ask you for the password of the user you want to connect to the VM with. -K will ask you for the password of the sudo user (can be the same as the previous one). If you have a ssh key already set up, you can remove it.

You also need to change the IP address of the VM in the ansible/hosts file.

Manual deployment

• sudo apt update to update the package list
• sudo apt upgrade to upgrade the packages
• Create the ./ssh/authorized_keys file and copy the content of the ./ansible/authorized_keys file into it. (You must have the ssh folder in the machine)

  mkdir -p ~/.ssh
  chmod 0700 ~/.ssh
  cp ./ansible/authorized_keys ~/.ssh/authorized_keys
  chmod 0600 ~/.ssh/authorized_keys

• Install apache2-utils and remove old versions of docker

sudo apt install apache2-utils
sudo apt remove docker.io docker-doc docker-compose docker-compose-v2 podman-docker
sudo apt install ca-certificates curl gnupg

• Add Docker’s official GPG key

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

• Add the Docker repository to APT sources

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

• Install Docker Engine and dependencies

sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

• Create the docker group and add your user

sudo groupadd docker
sudo usermod -aG docker $USER

• Restart the service and enabling it

sudo systemctl restart docker
sudo systemctl enable docker
sudo systemctl enable containerd

• Clone the repositories

rm -rf ~/heig-vd-dai-course-code-examples
rm -rf ~/dai-pw04
git clone https://github.com/heig-vd-dai-course/heig-vd-dai-course-code-examples.git ~/heig-vd-dai-course-code-examples
git clone https://github.com/heig-lherman/dai-pw04.git ~/dai-pw04

• You must configure the followig files:

  • ~/heig-vd-dai-course-code-examples/23-practical-work-4/traefik-secure/.env
  • ~/heig-vd-dai-course-code-examples/23-practical-work-4/whoami-with-traefik-secure/.env

• Create ~/heig-vd-dai-course-code-examples/23-practical-work-4/traefik-secure/secrets and configure the username and password

mkdir ~/heig-vd-dai-course-code-examples/23-practical-work-4/traefik-secure/secrets
htpasswd -c secrets/auth-users.txt admin

• Run all the containers

cd ~/heig-vd-dai-course-code-examples/23-practical-work-4/traefik-secure/
docker-compose up -d
cd ~/

cd ~/heig-vd-dai-course-code-examples/23-practical-work-4/whoami-with-traefik-secure/
docker-compose up -d
cd ~/

cd ~/dai-pw04/
docker-compose up -d
cd ~/

DNS configuration

We use terraform for the configuration of our DNS rules on the cloudflare platform, the configuration is available in the terraform folder, which anyone can use to configure their own DNS rules for the app, provided they change the secrets to point to their own respective accounts.

As for the actual configuration itself, the application requires a simple A record pointing to the server's IP address, defined as below (for the api.dai.heig.lutonite.dev domain):

api.dai.heig.lutonite.dev. 300 IN A 185.144.38.63

In cloudflare, we disabled the proxy since we are using traefik to handle the SSL certificates, as well as the redirection to the proper services, and we didn't want cloudflare to intervene in the TLS chain.

We have added additional domain names all pointing to the same IP address for access to the whoami application as well as the traefik dashboard.