From 3fce3e400fd44d3b6f345a31413e0ad2b7724107 Mon Sep 17 00:00:00 2001
From: alex <alex@alexloehr.net>
Date: Mon, 17 Nov 2025 17:42:43 +0000
Subject: [PATCH] GS-2373
---
README.md | 232 +++++++++++++++++++++++++++++++++++++++++++++++++++------
1 files changed, 205 insertions(+), 27 deletions(-)
diff --git a/README.md b/README.md
index a01a5c8..294f31e 100644
--- a/README.md
+++ b/README.md
@@ -1,49 +1,199 @@
# 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.)
+
+
+### ILIAS DB Access
+
+Globus-ILIAS-Rest needs access to the ILIAS DB.
+The DB credentials are defined in the settings file `settings.$NODE_ENV.json`.
+
+
+### Software
+
+- node.js v22.x
+- npm (included in node.js)
+
+#### Installing node.js
+
+__Do not install node.js from a package manager!__
+These node versions are generally outdated and cannot be used to run Globus-ILIAS-Rest.
+
+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
+
+
+#### Installing pm2
+
+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
+ 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
+
+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 /popcorn http://localhost:4101
+
+
+
## Setup
-### Env und Settings
+### Env
-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.
+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!__
-### Service
-Der REST-Service an sich muss auf dem gleichen Rechner laufen auf dem auch die ILIAS DB läuft (ansonsten die Config anpassen).
+### Install files
- node app.js
+Install Globus-ILIAS-Rest using git.
-bzw. bei Nutzung von pm2 (empfohlen)
+ 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
-### Apache Config
-Apache muss als Proxy für globus-ilias-rest fungieren und Verbindungen an diesen weiterreichen.
-
-__ACHTUNG__
-Der Service __muss__ unter https laufen. Ansonsten kann das AUTH-TOKEN ausgelesen werden.
-
-TODO
## 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):
@@ -52,16 +202,44 @@
Die Antwort prettyfeien:
curl localhost:4101/users?token=AUTHTOKEN | jq .
-
-### Routes
+### globusfm-dev2
-Verfügbare Routen sind:
+Kann zugegriffen werden über
- GET /users
- GET /users/count
- GET /user/login/:login
- GET /user/userId/:userId
+ https://globusfm-dev2.minervis.com/popcorn/users?token=$TOKEN
+#### Testing PHP Component
+
+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
+
+Die API dann über:
+https://globusfm-dev2.minervis.com/popcorn/api/user/userid/573?token=$TOKEN
+
+__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