globus/globus-ilias-rest.git

parent: df46e717 | patch | commit | ignore whitespace

alex

2025-11-17 0a2afeb91d1ff61f9d9446999f8550969871becf

GS-2373

1 files added

2 files modified

1 files renamed

	README.md	215 ●●●●● patch \| view \| raw \| blame \| history
	README_alt.md	127 ●●●●● patch \| view \| raw \| blame \| history
	php/globus-ilias-rest/login.php	patch \| view \| raw \| blame \| history
	settings.default.json	2 ●●●●● patch \| view \| raw \| blame \| history

 README.md

@@ -1,81 +1,98 @@
# 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
### Software

### Env und Settings
- node.js v22.x
- npm (included in node.js)

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.
#### 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


### Service
#### Installing pm2

Der REST-Service an sich muss auf dem gleichen Rechner laufen auf dem auch die ILIAS DB läuft (ansonsten die Config anpassen).
Depending on how node.js was installed pm2 is installed differently.

    node app.js
If using a local node.js (e.g. using nvm):

bzw. bei Nutzung von pm2 (empfohlen)
    npm i -g pm2

    pm2 start app.js --name globus-ilias-rest
    pm2 save
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 Komponente
#### PHP Component

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).
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 wich __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.

#### Testen

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!
__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
@@ -83,14 +100,96 @@
    ProxyPassReverse /popcorn http://localhost:4101


_testen_

    https://globusfm-dev2.minervis.com/popcorn/users?token=AUTHTOKEN


## Setup


### Env und Settings

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 the files 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):

@@ -103,24 +202,24 @@

### 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



 README_alt.md

New file
@@ -0,0 +1,127 @@
# Globus-ILIAS-Rest

REST Service für POPCORN -> ILIAS.
Stellt in ILIAS-SOAP fehlende Funktionen bereit für POPCORN (GS-2101).


## Voraussetzungen

- node >= v22
- pm2


## Setup

### 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.


### Service

Der REST-Service an sich muss auf dem gleichen Rechner laufen auf dem auch die ILIAS DB läuft (ansonsten die Config anpassen).

    node app.js

bzw. bei Nutzung von pm2 (empfohlen)

    pm2 start app.js --name globus-ilias-rest
    pm2 save



### PHP Komponente

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).

    cd $ILIASBASEDIR
    cp -ar $RESTPROJ/php/globus-ilias-rest globus-ilias-rest

#### PROBLEM mit api.php

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.

#### Testen

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!



### 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.

#### MOds aktivieren

    a2enmod proxy
    a2enmod proxy_http

#### Apache Config anpassen

z.B. unter `/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


_testen_

    https://globusfm-dev2.minervis.com/popcorn/users?token=AUTHTOKEN


## Usage

Es wird ein Auth-Token gebraucht um den Service zu benutzen. Dieses wird in settings.js definiert.

Dann kann der Service angesprochen werden (test mit curl):

    curl localhost:4101/users?token=AUTHTOKEN

Die Antwort prettyfeien:

    curl localhost:4101/users?token=AUTHTOKEN | jq .


### globusfm-dev2

Kann zugegriffen werden über 

    https://globusfm-dev2.minervis.com/popcorn/users?token=$TOKEN


## Routes

Verfügbare Routen sind:

    GET /users
    GET /users/count
    GET /user/login/:login
    GET /user/userId/:userId

    GET /kurs
    GET /kurs/items/:ref_id
    GET /kurs/teilnehmer/:ref_id
    GET /kurs/teilnehmer/:ref_id/count

    ...



 php/globus-ilias-rest/login.php


 settings.default.json

@@ -14,7 +14,7 @@
   },
   "ilias": {
      "urlDoc": "Url of custom ILIAS PHP file",
      "url": "http://192.168.178.84:8060/globus-ilias-rest/api.php",
      "url": "http://192.168.178.84:8060/globus-ilias-rest/login.php",
      "iliastoken": "jkhHKhui899HUKHBzGHtgoiedko2393490",
      "iliasTokenComment": "Token muss bei Änderungen nach php/globus-ilias-rest/token kopiert werden"
   }

			@@ -1,81 +1,98 @@
			# 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
			### Software

			### Env und Settings
			- node.js v22.x
			- npm (included in node.js)

			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.
			#### 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


			### Service
			#### Installing pm2

			Der REST-Service an sich muss auf dem gleichen Rechner laufen auf dem auch die ILIAS DB läuft (ansonsten die Config anpassen).
			Depending on how node.js was installed pm2 is installed differently.

			node app.js
			If using a local node.js (e.g. using nvm):

			bzw. bei Nutzung von pm2 (empfohlen)
			npm i -g pm2

			pm2 start app.js --name globus-ilias-rest
			pm2 save
			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 Komponente
			#### PHP Component

			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).
			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 wich __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.

			#### Testen

			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!
			__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
			@@ -83,14 +100,96 @@
			ProxyPassReverse /popcorn http://localhost:4101


			_testen_

			https://globusfm-dev2.minervis.com/popcorn/users?token=AUTHTOKEN


			## Setup


			### Env und Settings

			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 the files 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):

			@@ -103,24 +202,24 @@

			### 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

New file
			@@ -0,0 +1,127 @@
			# Globus-ILIAS-Rest

			REST Service für POPCORN -> ILIAS.
			Stellt in ILIAS-SOAP fehlende Funktionen bereit für POPCORN (GS-2101).


			## Voraussetzungen

			- node >= v22
			- pm2


			## Setup

			### 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.


			### Service

			Der REST-Service an sich muss auf dem gleichen Rechner laufen auf dem auch die ILIAS DB läuft (ansonsten die Config anpassen).

			node app.js

			bzw. bei Nutzung von pm2 (empfohlen)

			pm2 start app.js --name globus-ilias-rest
			pm2 save



			### PHP Komponente

			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).

			cd $ILIASBASEDIR
			cp -ar $RESTPROJ/php/globus-ilias-rest globus-ilias-rest

			#### PROBLEM mit api.php

			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.

			#### Testen

			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!



			### 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.

			#### MOds aktivieren

			a2enmod proxy
			a2enmod proxy_http

			#### Apache Config anpassen

			z.B. unter `/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


			_testen_

			https://globusfm-dev2.minervis.com/popcorn/users?token=AUTHTOKEN


			## Usage

			Es wird ein Auth-Token gebraucht um den Service zu benutzen. Dieses wird in settings.js definiert.

			Dann kann der Service angesprochen werden (test mit curl):

			curl localhost:4101/users?token=AUTHTOKEN

			Die Antwort prettyfeien:

			curl localhost:4101/users?token=AUTHTOKEN \| jq .


			### globusfm-dev2

			Kann zugegriffen werden über

			https://globusfm-dev2.minervis.com/popcorn/users?token=$TOKEN


			## Routes

			Verfügbare Routen sind:

			GET /users
			GET /users/count
			GET /user/login/:login
			GET /user/userId/:userId

			GET /kurs
			GET /kurs/items/:ref_id
			GET /kurs/teilnehmer/:ref_id
			GET /kurs/teilnehmer/:ref_id/count

			...

			@@ -14,7 +14,7 @@
			},
			"ilias": {
			"urlDoc": "Url of custom ILIAS PHP file",
			"url": "http://192.168.178.84:8060/globus-ilias-rest/api.php",
			"url": "http://192.168.178.84:8060/globus-ilias-rest/login.php",
			"iliastoken": "jkhHKhui899HUKHBzGHtgoiedko2393490",
			"iliasTokenComment": "Token muss bei Änderungen nach php/globus-ilias-rest/token kopiert werden"
			}