From 3d93817b855dcbe1c4d2573faa2901ae3db0f7d8 Mon Sep 17 00:00:00 2001
From: alex <alex@alexloehr.net>
Date: Fri, 28 Nov 2025 10:29:25 +0000
Subject: [PATCH] audit

---
 README.md |  238 ++++++++++++++++++++++++++++++++++++++++++++++++++---------
 1 files changed, 200 insertions(+), 38 deletions(-)

diff --git a/README.md b/README.md
index 21ddce3..04737e4 100644
--- a/README.md
+++ b/README.md
@@ -1,82 +1,244 @@
 # 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
 
 
-### Apache Config
+#### Installing pm2
 
-Apache muss als Proxy für globus-ilias-rest fungieren und Verbindungen an diesen weiterreichen.
+Depending on how node.js was installed pm2 is installed differently.
 
-__ACHTUNG__
-Der Service __muss__ unter https laufen. Ansonsten kann das AUTH-TOKEN ausgelesen werden.
+If using a local node.js (e.g. using nvm):
 
-#### MOds aktivieren
+    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
+    chown -R www-data:www-data globus-ilias-rest
+
+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.
+
+__Make sure that this `.htaccess` Apache rule is active and prevents the file from beeing read by the webserver.__
+
+
+
+
+#### Apache webserver
+
+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).
+
+__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
     ProxyPass /popcorn http://localhost:4101         
-    ProxyPassReverse / http://localhost:4101
+    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 and all components are accessible.
+
+Inside Globus-ILIAS-Rest dir run:
+
+    npm run test-connect
+
+All tests must succeed without errors.
+
+
+__Note__
+The tests for "the rest service" can only succeed when the rest service is running (see below).
+
+
+
+
+## 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):
+Access REST API using curl:
 
-    curl localhost:4101/users?token=AUTHTOKEN
+    curl localhost:4101/api/user?token=AUTHTOKEN
 
-Die Antwort prettyfeien:
+Prettify the response:
 
-    curl localhost:4101/users?token=AUTHTOKEN | jq .
-   
+    curl localhost:4101/api/user?token=AUTHTOKEN | jq .
 
 
-### Routes
 
-Verfügbare Routen sind:
 
-    GET /users
-    GET /users/count
-    GET /user/login/:login
-    GET /user/userId/:userId
+## Manual testing
 
+Some example URLs for manual testing.
+
+### Test for globusfm-dev2
+
+Can be accessed by 
+
+    curl https://globusfm-dev2.minervis.com/popcorn/api/user?token=$TOKEN
+    curl https://globusfm-dev2.minervis.com/popcorn/api/user/userid/573?token=$TOKEN
+
+#### Testing PHP Component
+
+    curl https://globusfm-dev2.minervis.com/globus-ilias-rest/login.php?token=$ILIASTOKEN&command=getUser&usr_id=573
+
+
+
+
+## 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