From 3d646156c378c6182e55c673c118c23d53ff0a05 Mon Sep 17 00:00:00 2001
From: alex <alex@alexloehr.net>
Date: Mon, 17 Nov 2025 17:36:00 +0000
Subject: [PATCH] GS-2373
---
README.md | 228 ++++++++++++++++++++++++++++++++++++++++++++------------
1 files changed, 179 insertions(+), 49 deletions(-)
diff --git a/README.md b/README.md
index fc21d03..294f31e 100644
--- a/README.md
+++ b/README.md
@@ -1,70 +1,104 @@
# Globus-ILIAS-Rest
-REST Service für POPCORN -> ILIAS.
-Stellt in ILIAS-SOAP fehlende Funktionen bereit für POPCORN (GS-2101).
+REST service for POPCORN -> ILIAS sync.
+
+Globus-ILIAS-Rest provides function for accessing ILIAS through a rest api.
-## Voraussetzungen
+## Prerequisites
-- node >= v22
-- pm2
+### ILIAS
+
+Globus-ILIAS-Rest must run on the same host the ILIAS installation is running on.
+(Theoretically it can also run on a different host but this is untested.)
-## Setup
+### ILIAS DB Access
-### Env und Settings
-
-Als Erstes wird die ENV Variable "NODE_ENV" gebraucht. Diese muss gesetzt sein.
-Je nach ENV (dev, test, prod, ...) muss dann auch die settings Datei angepasst werden.
+Globus-ILIAS-Rest needs access to the ILIAS DB.
+The DB credentials are defined in the settings file `settings.$NODE_ENV.json`.
-### Service
+### Software
-Der REST-Service an sich muss auf dem gleichen Rechner laufen auf dem auch die ILIAS DB läuft (ansonsten die Config anpassen).
+- node.js v22.x
+- npm (included in node.js)
- node app.js
+#### Installing node.js
-bzw. bei Nutzung von pm2 (empfohlen)
+__Do not install node.js from a package manager!__
+These node versions are generally outdated and cannot be used to run Globus-ILIAS-Rest.
- pm2 start app.js --name globus-ilias-rest
- pm2 save
+Download and install from the node.js website:
+https://nodejs.org/en/download
+
+or
+
+Use tools like `nvm` to handle the installation of the required version.
+https://github.com/nvm-sh/nvm
-### PHP Komponente
+#### Installing pm2
-globus-ilias-rest benötigt eine PHP Komponente um die ILIAS internen Funktionen nutzen zu können.
-Dazu den Ordner "php/globus-ilias-rest" im Projektverzeichnis symlinken in den ILIAS Basisordner (wo sich auch ilias.php befindet).
+Depending on how node.js was installed pm2 is installed differently.
+If using a local node.js (e.g. using nvm):
+
+ npm i -g pm2
+
+If using a global node.js
+
+ sudo npm i -g pm2
+
+Registering pm2 to start on system boot.
+
+ pm2 startup
+
+_Then follow the instructions provided by pm2._
+
+
+
+#### PHP Component
+
+globus-ilias-rest requires a PHP compoentent for accessing ILIAS internal functions.
+This component needs to be copied into the base dir of ILIAS (`$ILIASBASEDIR`).
+
+Starting from the installation dir of Globus-ILIAS-Rest
+
+ cp -ar php/globus-ilias-rest $ILIASBASEDIR/.
cd $ILIASBASEDIR
- cp -ar $RESTPROJ/php/globus-ilias-rest globus-ilias-rest
+ chown -R www-data:www-data globus-ilias-rest
-__PROBLEM mit api.php__
+The copied folder contains a file named `token`. This file contains an access token which __must be kept secret__.
+The file `token` is protected by a `.htaccess` rule which prevents the webserver from reading the file.
-Auf globusfm-dev2 gibt es das Problem, dass die api.php nicht aufgerufen werden kann. Es erfolgt immer ein Redirect auf login.php.
-Das passiert nicht auf DEV.
-
-_Workaround_
-
-api.php zu login.php umbenennen.
-Pfad in den settings entsprechend anpassen.
+__Make sure that this `.htaccess` Apache rule is active and prevents the file from beeing read by the webserver.__
-### Apache Config
-Apache muss als Proxy für globus-ilias-rest fungieren und Verbindungen an diesen weiterreichen.
+#### Apache webserver
-__ACHTUNG__
-Der Service __muss__ unter https laufen. Ansonsten kann das AUTH-TOKEN ausgelesen werden.
+Apache needs to work as a reverse proxy for Globus-ILIAS-Rest.
+This way Globus-ILIAS-Rest can be accessed through the same URL as the ILIAS Installation (including https).
-#### MOds aktivieren
+__ATTENTION__
+The service __must__ run under https. Otherwise, the AUTH-TOKEN used by Globus-ILIAS-Rest is not secure.
+(as of now this is given for both ILIAS installations)
+
+##### Enable mod_proxy
+
+Enable Apache mods if not enabled yet
a2enmod proxy
a2enmod proxy_http
-#### Apache Config anpassen
+##### Apache Config
-z.B. unter `/etc/apache2/sites-available/globusfm-dev2.minervis.com.conf`
+The apache config must be changed to proxy all requests going to "https://$ILIASURL/popcorn/" to Globus-ILIAS-Rest.
+
+Insert into apache config of the site:
+e.g. for `/etc/apache2/sites-available/globusfm-dev2.minervis.com.conf`
# Proxy all requests to /popcorn/... to the globus-ilias-rest service
ProxyPreserveHost On
@@ -72,14 +106,94 @@
ProxyPassReverse /popcorn http://localhost:4101
-_testen_
- https://globusfm-dev2.minervis.com/popcorn/users?token=AUTHTOKEN
+
+
+## Setup
+
+### Env
+
+Set `NODE_ENV` env var.
+E.g. in `.bashrc`.
+
+For Test installation
+
+ NODE_ENV=test
+
+For production installation.
+
+ NODE_ENV=prod
+
+__NODE_ENV must be set before starting the application!__
+
+
+
+### Install files
+
+Install Globus-ILIAS-Rest using git.
+
+ git clone https://$USER@gitblit.minervis.com/r/globus/globus-ilias-rest.git
+ cd globus-ilias-rest
+
+Install dependencies
+
+ npm i
+
+Copy the required .env file.
+
+ cp vue/.env.$NODE_ENV vue/.env
+
+Build frontend
+
+ npm run build
+
+
+
+### Run a self test
+
+Globus-ILIAS-Rest has a build-in testing tool to check if everything works correctly.
+
+Inside Globus-ILIAS-Rest dir run:
+
+ npm run test-connect
+
+All tests must succeed without errors.
+
+
+
+
+## Running
+
+The best way to run Globus-ILIAS-Rest is by running it through pm2 (node process manager).
+pm2 automatically provides some useful features like restarting the app if it crashes and more.
+
+
+## Running the app through pm2
+
+Starting from inside the installation dir of Globus-ILIAS-Rest.
+
+ pm2 start app.js --name globus-ilias-rest
+
+Check if the app is running correctly
+
+ pm2 ls
+
+_Check if status is "online"._
+
+
+Save the app startup config so that it can be restored on system boot.
+
+ pm2 save
+
+
+
+
## Usage
-Es wird ein Auth-Token gebraucht um den Service zu benutzen. Dieses wird in settings.js definiert.
+For accessing the service a auth-token is required.
+This token is defined in the config file `settings.$NODE_ENV.json`.
Dann kann der Service angesprochen werden (test mit curl):
@@ -92,24 +206,40 @@
### globusfm-dev2
-Kann zugegriffen werden über
+Kann zugegriffen werden über
https://globusfm-dev2.minervis.com/popcorn/users?token=$TOKEN
-## Routes
+#### Testing PHP Component
-Verfügbare Routen sind:
+Folgende URL sollte dann funktionieren für die PHP Komponente:
+https://globusfm-dev2.minervis.com/globus-ilias-rest/login.php?token=$PHPTOKEN&command=getUser&usr_id=573
- GET /users
- GET /users/count
- GET /user/login/:login
- GET /user/userId/:userId
+Die API dann über:
+https://globusfm-dev2.minervis.com/popcorn/api/user/userid/573?token=$TOKEN
- GET /kurs
- GET /kurs/items/:ref_id
- GET /kurs/teilnehmer/:ref_id
- GET /kurs/teilnehmer/:ref_id/count
+__Achtung__ die Tokens sind unterschiedlich!
+### Testing Apache
+
+ https://globusfm-dev2.minervis.com/popcorn/users?token=AUTHTOKEN
+
+
+
+
+## Other
+
+### Logs
+
+To prevent logs from growing too big the file `$INSTALLDIR/log.log` should be included into a logrotation job.
+
+Furthermore `pm2` also does some logging.
+`pm2` logs can be cleared by running
+
+ pm2 flush
+
+Alternatively `pm2` logging also can be turned off (not advised).
+To do this add the param `--disable-logs` when running Globus-ILIAS-Rest through `pm2`.
--
Gitblit v1.8.0