| | |
|---|
| | | # 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. |
|---|
| | | |
|---|
| | | 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. |
|---|
| | | |
|---|
| | | 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): |
|---|
| | | |
|---|
| | | curl localhost:4101/users?token=AUTHTOKEN |
|---|
| | | |
|---|
| | | Die Antwort prettyfeien: |
|---|
| | | |
|---|
| | | ### Routes |
|---|
| | | curl localhost:4101/users?token=AUTHTOKEN | jq . |
|---|
| | | |
|---|
| | | Verfügbare Routen sind: |
|---|
| | | |
|---|
| | | GET /users |
|---|
| | | GET /users/count |
|---|
| | | GET /user/login/:login |
|---|
| | | GET /user/userId/:userId |
|---|
| | | ### globusfm-dev2 |
|---|
| | | |
|---|
| | | Kann zugegriffen werden über |
|---|
| | | |
|---|
| | | 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`. |
|---|
| | | |
|---|
