Ga naar inhoud

Getting started

To get started with this project some things need te be setup, some for local development and some for access to third party services.

Setup

System requirements

  • Docker + docker-compose installed, easiest way is to follow this guide;
  • Entry in the systems hostfile to map metriek.local to 127.0.0.1
    • MacOS
      • Open a terminal and run sudo nano /etc/hosts
      • Add 127.0.0.1 metriek.local
      • Save
    • Windows
      • Follow this guide
      • Add a mapping from metriek.local to 127.0.0.1

When using WSL on Windows replace 127.0.0.1 with the IP address of your WSL instance.

docker-compose.yaml

The docker-compose-yaml file contains all services needed for the application, here's what they do and why they're needed:

  • nginx: Nginx is a webserver. It handles all incoming traffic on port 80/433 of the vm (or metriek.local) and redirects it to the correct service. /api is redirected to the API, /docs is redirected to the documentation, etc...
  • certbot: Certbot (LetsEncrypt) is a tool that creates and refreshes free SSL certifications. It has no purpose in local development.
  • app: The backend application. The container contains all necessary packages to run the Python package and communicate with the database.
  • portal: The frontend application. Runs in a container based on Node v18.
  • db: serves a local Azure SQL database, usefull in a playground environment.

Startup

  • Copy .env.example to .env and add all values;
  • Copy nginx/.env.example to nginx/.env (and add all values);
  • Run docker-compose up -d to start all containers (depending on your docker version this could also be docker compose up -d);
  • Open https://baa.metriek.tech in a browser

Why metriek.local?

Using metriek.local make it easy to locally mimic a deployment on a VM. Furthermore, Exact Online Apps require a redirect URI for the auth flow and it doesn't accept http://localhost and thus requires a 'real' domain to function, metriek.local offers just that.

Local SSL

Some services require HTTPS on metriek.local. To enable it, run:

  • Install mkcert;
  • Run mkcert -key-file nginx/local/ssl/key.pem -cert-file nginx/local/ssl/cert.pem -install metriek.local from the root of the project;
  • Restart the Nginx container with docker-compose up -d --force-recreate nginx

WSL

When running WSL on windows the above steps generated SSL certificates on the Linux side. To have your (Windows) browser trust the certificate copy /nginx/local/ssl/cert.pem to the Windows (i.e. in C:/Desktop) side and double click it to install the certificate in Windows.