From 3a044cf4578b313ac6fa85218c8a92fe5bce7c5f Mon Sep 17 00:00:00 2001 From: Tibo De Peuter Date: Fri, 16 May 2025 12:06:16 +0200 Subject: [PATCH] Update --- Administrator:-Productie-omgeving.md | 255 ++++++++++++++++++++++++--- 1 file changed, 226 insertions(+), 29 deletions(-) diff --git a/Administrator:-Productie-omgeving.md b/Administrator:-Productie-omgeving.md index bc286c4..8909561 100644 --- a/Administrator:-Productie-omgeving.md +++ b/Administrator:-Productie-omgeving.md @@ -2,7 +2,7 @@ Welkom bij de Dwengo-1 Administrator handleiding. Deze handleiding beschrijft de **Doelpubliek** -Deze handleiding is gericht aan de gebruikers die hun eigen Dwengo-1 server willen installeren, instellen en optimaliseren. Voor meer informatie over de gebruikersinterface, zie [de handleiding voor leerkrachten](#TODO) en [de handleiding voor leerlingen](#TODO). +Deze handleiding is gericht aan de gebruikers die hun eigen Dwengo-1 server willen installeren, instellen en optimaliseren. Voor meer informatie over de gebruikersinterface, zie [de handleiding voor leerkrachten](https://github.com/SELab-2/Dwengo-1/wiki/Leerkracht:-Dwengo%E2%80%901-gebruiken) en [de handleiding voor leerlingen](https://github.com/SELab-2/Dwengo-1/wiki/Leerlingen:-Dwengo%E2%80%901-gebruiken). ## Installatie en server configuratie @@ -20,9 +20,188 @@ Voor de beste performantie, stabiliteit en functionaliteit raden we de volgende Er zijn verschillende manieren om Dwengo-1 te installeren afhankelijk van uw voorkeuren, vereisten en toepassingen. -Als u een geautomatiseerde installatie verkiest, dan heeft u keuze uit: +Voorlopig worden de volgende methodes ondersteund: -- gebruik de [Dwengo-1 Docker image(s)](#TODO). Deze image is ... WIP +- Docker Compose en Dwengo-1 Docker images +- Docker Compose en zelfgebouwde Dwengo-1 images vanaf de broncode +- Handmatige installatie vanaf de broncode + +#### Docker Compose en Dwengo-1 Docker images + +De snelste manier om Dwengo-1 te installeren is door gebruik te maken van de kant-en-klare Docker images. + +1. Installeer Docker en Docker Compose op je systeem (zie [Docker](https://docs.docker.com/get-docker/) en [Docker Compose](https://docs.docker.com/compose/)). +2.
Gebruik de volgende compose file: + Pas de nodige instelling aan! + + ```yaml + services: + web: + image: ghcr.io/selab-2/dwengo-1/frontend:latest + restart: unless-stopped + networks: + - dwengo-1 + labels: + - 'traefik.enable=true' + - 'traefik.http.routers.web.rule=PathPrefix(`/`)' + - 'traefik.http.services.web.loadbalancer.server.port=8080' + + api: + image: ghcr.io/selab-2/dwengo-1/backend:latest + restart: unless-stopped + volumes: + # TODO Replace with environment keys + - ./backend/.env:/app/dwengo/backend/.env + depends_on: + - db + - logging + networks: + - dwengo-1 + labels: + - 'traefik.enable=true' + - 'traefik.http.routers.api.rule=PathPrefix(`/api`)' + - 'traefik.http.services.api.loadbalancer.server.port=3000' + + db: + image: postgres:latest + ports: + - '5431:5432' + restart: unless-stopped + volumes: + - dwengo_postgres_data:/var/lib/postgresql/data + environment: + POSTGRES_USER: postgres + POSTGRES_PASSWORD: postgres + POSTGRES_DB: postgres + networks: + - dwengo-1 + + keycloak-db: + image: postgres:latest + ports: + - '5442:5432' # Port number 10 higher than normal postgres ports + restart: unless-stopped + volumes: + - dwengo_postgres_keycloak:/var/lib/postgresql/keycloak + environment: + POSTGRES_USER: keycloak + POSTGRES_PASSWORD: ChangeMe + POSTGRES_DB: keycloak + networks: + - dwengo-1 + + idp: # Based on: https://medium.com/@fingervinicius/easy-running-keycloak-with-docker-compose-b0d7a4ee2358 + image: quay.io/keycloak/keycloak:latest + ports: + - '7080:7080' + # - '7443:7443' + restart: unless-stopped + command: ['start', '--http-port', '7080', '--https-port', '7443', '--import-realm'] + networks: + - dwengo-1 + labels: + - 'traefik.enable=true' + - 'traefik.http.routers.idp.rule=PathPrefix(`/idp`)' + - 'traefik.http.services.idp.loadbalancer.server.port=7080' + - 'traefik.http.routers.block-admin.rule=PathPrefix(`/idp/admin`)' + - 'traefik.http.routers.block-admin.service=web' + depends_on: + - keycloak-db + volumes: + - /etc/keycloak:/keycloak + env_file: + - ./config/idp/.env + environment: + KC_HOSTNAME: 'YOUR-DOMAINNAME' + PROXY_ADDRESS_FORWARDING: 'true' + KC_PROXY_HEADERS: 'xforwarded' + KC_HTTP_ENABLED: 'true' + KC_HTTP_RELATIVE_PATH: '/idp' + KC_HTTPS_CERTIFICATE_FILE: '/keycloak/cert.pem' + KC_HTTPS_CERTIFICATE_KEY_FILE: '/keycloak/key.pem' + KC_HTTP_MAX_QUEUED_REQUESTS: 30 # Prevent overload situations by limiting number of requests + KC_DB: 'postgres' + KC_DB_USERNAME: 'keycloak' + KC_DB_PASSWORD: 'CHANGEME' + KC_DB_URL: 'jdbc:postgresql://keycloak-db:5432/keycloak' + + reverse-proxy: + image: traefik:v3.3 + ports: + - '80:80/tcp' + - '443:443/tcp' + command: + # Add Docker provider + - '--providers.docker=true' + - '--providers.docker.exposedbydefault=false' + + # Add web entrypoint + - '--entrypoints.web.address=:80/tcp' + - '--entrypoints.web.http.redirections.entryPoint.to=websecure' + - '--entrypoints.web.http.redirections.entryPoint.scheme=https' + + # Add websecure entrypoint + - '--entrypoints.websecure.address=:443/tcp' + - '--entrypoints.websecure.http.tls=true' + - '--entrypoints.websecure.http.tls.certResolver=letsencrypt' + - '--entrypoints.websecure.http.tls.domains[0].main=sel2-1.ugent.be' + + # Certificates + - '--certificatesresolvers.letsencrypt.acme.httpchallenge=true' + - '--certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web' + - '--certificatesresolvers.letsencrypt.acme.email=timo.demeyst@ugent.be' + - '--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json' + restart: unless-stopped + volumes: + - /var/run/docker.sock:/var/run/docker.sock:ro + - dwengo_letsencrypt:/letsencrypt + networks: + - dwengo-1 + + logging: + image: grafana/loki:latest + ports: + - '9001:3102' + - '9095:9095' + command: -config.file=/etc/loki/config.yaml + restart: unless-stopped + volumes: + - ./config/loki/config.yml:/etc/loki/config.yaml + - dwengo_loki_data:/loki + networks: + - dwengo-1 + + dashboards: + image: grafana/grafana:latest + ports: + - '9002:3000' + restart: unless-stopped + volumes: + - dwengo_grafana_data:/var/lib/grafana + + volumes: + dwengo_grafana_data: + dwengo_letsencrypt: + dwengo_loki_data: + dwengo_postgres_keycloak: + + networks: + dwengo-1: + ``` +
+3. Configureer de applicatie aan de hand van [de configuratiehandleiding](#dwengo-1-configuratie). + +#### Docker Compose en zelfgebouwde Dwengo-1 images vanaf de broncode + +Als je de Dwengo-1 applicatie wilt draaien met Docker, maar je wilt zelf de images bouwen, dan kan je de volgende stappen volgen: + +1. Installeer Docker en Docker Compose op je systeem (zie [Docker](https://docs.docker.com/get-docker/) + en [Docker Compose](https://docs.docker.com/compose/)). +2. Clone deze repository. +3. Voer `docker compose -f compose.production.yml up --build` uit in de root van de repository. +4. Configureer de applicatie aan de hand van [de configuratiehandleiding](#dwengo-1-configuratie). + +#### Handmatige installatie vanaf de broncode Als u liever installeert vanaf de broncode, dan kan u Dwengo-1 opzetten vanaf scratch. Deze handleiding doorloopt alle stappen die nodig zijn om Dwengo-1 te installeren op Ubuntu 24.04 LTS met Nginx en PostgreSQL, gebruik makende van [de Dwengo-1 .tar](#TODO-link-naar-github-release). Deze methode wordt aangeraden om Dwengo-1 te installeren. @@ -30,42 +209,23 @@ Deze handleiding biedt een overzicht van de stappen die je moet doorlopen om Dwe **Vereisten voor handmatige installatie** -WIP - -**Nginx Web server configuratie** - -WIP - -**Keycloak (Identity Provider) configuratie** - -WIP (zie ook [Comment by @geraldschmittinger](https://github.com/SELab-2/Dwengo-1/pull/74#discussion_r1980282845)) - -**Alternatieve Identity Providers configureren** - -WIP Hoe kan de systeembeheerder hun eigen IDP in het project "pluggen"? - -**SSL aanzetten** - -WIP - -### Voorbeeldinstallatie op Ubuntu 22.04 LTS - -De packages die nodig zijn voor een typische Dwengo-1 installatie, gebruik makend van Nginx en PostgreSQL, kunnen geïnstalleerd worden door het volgende commando in een terminal uit te voeren: +De packages die nodig zijn voor een typische Dwengo-1 installatie, gebruikmakend van Nginx en PostgreSQL, kunnen geïnstalleerd worden door het volgende commando in een terminal uit te voeren: ```shell sudo apt update && sudo apt upgrade sudo apt install nginx postgres ``` - - Dit commando installeert de packages voor de basis van Dwengo-1. Houd er rekening mee dat als u plant een bijzondere configuratie te gebruiken, het mogelijk is dat u extra packages nodig zal hebben. +**PostgreSQL configuratie** + Nu moet u een database gebruiker en database maken via de Postgres command line interface. De database tabellen zullen gemaakt worden door Dwengo-1 als je de applicatie voor de eerste keer opstart. Om Postgres in command line mode te starten, gebruik het volgende commando: ```shell psql -``` +``` Er verschijnt een prompt `>`. Vul daar de volgende lijnen in, waarin je `username` en `password` vervangt door de juiste waarden, en bevestig de lijnen met de Enter toets: @@ -75,6 +235,24 @@ CREATE USER.... WIP Je kan het prompt stoppen door `quit;` in te geven. +**Keycloak (Identity Provider) installatie & configuratie** + +Dwengo-1 maakt gebruik van Keycloak als Identity Provider (IDP). Zie Keycloak's [installatiehandleidingen](https://www.keycloak.org/guides#getting-started) voor meer informatie over hoe je Keycloak kan installeren. + +De huidige configuratie draait Keycloak in ontwikkelmodus. Indien Dwengo-1 in productie draait, moet deze configuratie aangepast worden. Zie [Configuring Keycloak for production](https://www.keycloak.org/server/configuration-production) voor meer informatie. + +**Alternatieve Identity Providers configureren** + +Dwengo-1 laat toe om alternatieve Identity Providers te gebruiken. Elke Identity Provider die de OpenID Connect standaard volgt, kan gebruikt worden. + +Er werden nog geen alternatieve Identity Providers getest. Heb je een alternatieve Identity Provider getest? [Laat het ons weten.](https://github.com/SELab-2/Dwengo-1/blob/dev/CONTRIBUTING.md) + +**Caching configureren** + +WIP + +**Broncode voorbereiden** + Download nu een archief van de laatste Dwengo-1 versie: - Ga naar de [Dwengo-1 release pagina](#TODO-link-naar-releases). @@ -101,12 +279,32 @@ TODO Voorbeeld commando van chown commando **Backend** -WIP +```shell +npm run build +npm run start -w backend +``` **Frontend** +```shell +npm run build +npm run build -w frontend +``` + +De bestanden in `frontend/dist` kunnen nu gehost worden door een webserver, bijvoorbeeld Nginx. + +**Nginx Web server configuratie** + WIP +**SSL aanzetten** + +WIP + +### Voorbeeldinstallatie op Ubuntu 24.04 LTS + + + ## Dwengo-1 configuratie WIP @@ -121,5 +319,4 @@ Zie de respectievelijke informatie voor de gekozen IDP indien een aangepaste ins ## Onderhoud -WIP Hoe updaten bij nieuwe release? - +WIP Hoe updaten bij nieuwe release? \ No newline at end of file