Welkom bij de Dwengo-1 Administrator handleiding. Deze handleiding beschrijft de administratietaken voor Dwengo-1, het interactieve leerplatform. Dwengo-1 is een full-stack applicatie.
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 en de handleiding voor leerlingen.
Installatie en server configuratie
Systeemvereisten
Voor de beste performantie, stabiliteit en functionaliteit raden we de volgende systeemvereisten aan.
| Platform | Options |
|---|---|
| Operating System (64-bit) |
|
| Database | PostgreSQL 13/14/15/16/17 |
| Webserver | Nginx |
Installatie op Linux
Er zijn verschillende manieren om Dwengo-1 te installeren afhankelijk van uw voorkeuren, vereisten en toepassingen.
Voorlopig worden de volgende methodes ondersteund:
- 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.
-
Installeer Docker en Docker Compose op je systeem (zie Docker en Docker Compose).
-
Gebruik de volgende compose file:
Pas de nodige instelling aan!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: -
Configureer de applicatie aan de hand van de configuratiehandleiding.
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:
- Installeer Docker en Docker Compose op je systeem (zie Docker en Docker Compose).
- Clone deze repository.
- Voer
docker compose -f compose.production.yml up --builduit in de root van de repository. - Configureer de applicatie aan de hand van de configuratiehandleiding.
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. Deze methode wordt aangeraden om Dwengo-1 te installeren.
Deze handleiding biedt een overzicht van de stappen die je moet doorlopen om Dwengo-1 te installeren. Voor een handleiding specifiek voor je distributie, zie Voorbeeldinstallatie op Ubuntu 22.04 LTS.
Vereisten voor handmatige installatie
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:
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:
psql
Maak een nieuwe gebruiker aan in de databank.
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 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 voor meer informatie.
Alternatieve Identity Providers configureren
Dwengo-1 laat toe om alternatieve Identity Providers te gebruiken. Elke Identity Provider die de OpenID Connect (OIDC) standaard volgt, kan gebruikt worden.
Er werden nog geen alternatieve Identity Providers door Dwengo-1 getest, maar een overzicht van OIDC providers kan je hier terugvinden. Heb je een alternatieve Identity Provider getest? Laat het ons weten.
Caching configureren
We maken gebruik van Memcached. Voor meer informatie over de configuratie, zie Memcached documentatie.
Broncode voorbereiden
Download nu een archief van de laatste Dwengo-1 versie:
- Ga naar de Dwengo-1 release pagina.
- Vind de laatste release of een release naar uw keuze en download ofwel het
.tar.bz2of.ziparchief. - Dit download een bestand met als naam
dwengo-1-x.y.z.tar.bz2ofdwengo-1-x.y.z.zip(waarbijx.y.zeen versienummer is). - Extraheer de inhoud van het archief. Voer het juiste commando uit voor uw type archief:
tar -xjvf dwengo-1-x.y.z.tar.bz2
unzip dwengo-1-x.y.z.zip
- Dit pakt een map uit
dwengo-1. Kopieer de Dwengo-1 map naar zijn uiteindelijke bestemming in de Nginx configuratie. - Verander als laatste stap de eigenaar van de mappen naar jouw HTTP gebruiker.
Backend
npm run build
npm run start -w backend
Frontend
npm run build
npm run build -w frontend
De bestanden in frontend/dist kunnen nu gehost worden door een webserver, bijvoorbeeld Nginx.
Gebruikers beheren
Gebruikers worden beheerd via de Identity Provider (IDP) interface.
In de standaardinstallatie is dit Keycloak. Zie Managing Users - Keycloak voor meer informatie.
Zie de respectievelijke informatie voor de gekozen IDP indien een aangepaste installatie wordt gebruikt.
Onderhoud
Bij een nieuwe versie kunnen de volgende tips van pas komen:
- Neem backups van je huidige configuratiebestanden, waaronder omgevingsvariabelen.
- Als je containers gebruikt, stop ze met
docker ... down. - Over het algemeen is het verstandig om niet meer dan één major versie te updaten per keer. Voorlopig is er geen auto-upgrade functionaliteit, maar de meeste veranderingen zijn alsnog backwards compatibel.