tdpeuter/2025SELab2-project-Dwengo
tdpeuter/2025SELab2-project-Dwengo
1
Fork 0
Code Issues Releases 4 Packages 2 Wiki Activity

Update

Tibo De Peuter 2025-05-16 12:06:16 +02:00
parent b237f9d4bd
commit 3a044cf457
1 changed files with 226 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

255
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. <details><summary>Gebruik de volgende compose file:</summary>
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:
```
</details>
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?