From a380a465ce02059a630ef678fecd6666cbdf8f30 Mon Sep 17 00:00:00 2001
From: alex <alex@alexloehr.net>
Date: Fri, 28 Nov 2025 10:21:00 +0000
Subject: [PATCH] GS-2333
---
README.md | 235 +++++++++++++++++++++++++++++++++++++++++++++++++++++-----
1 files changed, 213 insertions(+), 22 deletions(-)
diff --git a/README.md b/README.md
index ec6a711..04737e4 100644
--- a/README.md
+++ b/README.md
@@ -1,53 +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.)
+
+
+### 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
-### Service
+### Env
-Der REST-Service an sich muss auf dem gleichen Rechner laufen auf dem auch die ILIAS DB läuft (ansonsten die Config anpassen).
+Set `NODE_ENV` env var.
+E.g. in `.bashrc`.
- node app.js
+For Test installation
-bzw. bei Nutzung von pm2 (empfohlen)
+ 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
-### Apache Config
-Apache muss als Proxy für globus-ilias-rest fungieren und Verbindungen an diesen weiterreichen.
-
-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):
+Access REST API using curl:
- curl localhost:4101/users?token=AUTHTOKEN
+ curl localhost:4101/api/user?token=AUTHTOKEN
+
+Prettify the response:
+
+ 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