server 0.9.0

One server to rule them all

New code base to handle all of the server-side logic and data handling in a modular way.

Table of contents

  1. Requirements
  2. Installation
  3. Documentation
  4. Config
  5. Usage
  6. Fast-server

Requirements

NodeJS is currently the only requirement: https://nodejs.org/en/download/

Installation

Pull the repository and then run the following command in the root folder using a command prompt:

npm install

This will install the dependencies in the local node_modules folder.

Documentation

Docs can be generated by running the following command:

npm run gendocs

This will build the docs using JSDoc and place them under docs/server/X, where X is the version specified inside of package.json.

Config

Adapt the config.js file in the root folder. Point the eyePath to the correct folder. Change port of the server if necessary. For help with debugging the reasoner you can set the consoleLogging option to true.

for the "uriqa" option: it should match the server's base url, it is used to match the prefixes of resources hosted on the server when the server is started. For instance uriqa: http://localhost:8000

CORS

In order to access the api through browser we have to enable CORS, the allowed origins can be found in the config.js file

Usage

In order to start the server, run the following in the root folder:

npm start

This starts the server using nodemon, any changes made to the code while the server is running will automatically restart the server, saving some labor of manually restarting.

Reasoner

In /reasoning/config.json routes can be specified, for example:

    "features": {
        "journey_moving": {
            "description": "journey moving",
            "inference": {
                "data": ["./reasoning/interim/steps/selectedSteps_Journey.n3", "./reasoning/oslo-descriptions/change-address-steps.ttl", "./reasoning/profile/*", "./reasoning/workflow-composer/gps-plugin_modified_noPermutations.n3"],
                "query": "./reasoning/journey/journeyGoal.n3",
                "output": "./data/temp/output.n3"
            }
        }
    }

In this case it sets up the route, localhost:8000/journey_moving. In 'inference', you can specify the data, query and output file for the reasoner (output is optional). The reasoner output is also sent back to the user.

Exposed data

The following routes can be used:

localhost:8000/shapes to expose the shapes data

localhost:8000/states to expose the states data

localhost:8000/steps to expose the steps data

Data manipulation

The next routes are placeholders to test functionality of adding information and seeing whether the reasoning is adapted.

localhost:8000/citizens view current information on the example user

localhost:8000/citizens/delete delete all the current information on the example user

Combining with user data

We have 2 types of data, one is stored locally on the server and the other will expect data provided through a post request, this is the entry point of user data. Both are enabled in this version. Due to the nature of the second data type most of the following subsections wont be possible, and if requested the server will fallback onto the first type. But the 2 most important routes are still accessable like this

curl --location --request POST 'localhost:8000/citizens/step/provideCitizenLastNameManually' --header 'Content-Type: text/plain' --data-raw 'Insert user data here'

curl --location --request POST 'localhost:8000/plan/journey_moving' --header 'Content-Type: text/plain' --data-raw 'Insert user data here'

Adding information

For adding information, there are currently two options:

localhost:8000/citizens/addInfo # add info on 1 or more steps
localhost:8000/citizens/step/<stepname> # add info for a specific step, specified in route

curl can be used to send PUT requests to these routes, see the following examples:

The following curl command can be used to add info to the example user.

curl --location --request POST 'localhost:8000/citizens/addInfo' --header 'Content-Type: application/json' --data-raw '{ "input": { "provideCitizenFirstNameManually": "123567" } }'

More than one step with corresponding values can be sent.

curl --location --request POST 'localhost:8000/citizens/addInfo' --header 'Content-Type: application/json' --data-raw '{ "input": { "provideCitizenPhoneNumberManually": "123567", "provideCitizenBirthPlaceManually": "test" } }'

Or, adding a value for a specific step using a specific route:

curl --location --request PUT 'localhost:8000/citizens/step/provideCitizenLastNameManually' --header 'Content-Type: application/json' --data-raw '{ "input": { "value": "123567" } }'

Editing info

Editing can be done by using the same routes in the same was as for adding information as described above. Consequently, if a value for the step already exists then the value will be changed to match the newly provided value instead.

Deleting info

Deleting info for steps can be done through the same routes as for editing and adding info, except there is no json input required for the specific route and the request should be of DELETE instead of PUT. Example:

curl --location --request DELETE 'localhost:8000/citizens/step/provideCitizenFirstNameManually' --data-raw ''

For one or more steps at the same time:

curl --location --request DELETE 'localhost:8000/citizens/deleteInfo' --header 'Content-Type: application/json' --data-raw '{
    "input": {
        "provideCitizenFirstNameManually": true,
        "provideCitizenLastNameManually": true,
        "provideCitizenPhoneNumberManually": true
    }
}'

Producing info used by a step

In order to produce info that is used by a step the following route can be used:

http://localhost:8000/citizens/step/<step>

eg:

http://localhost:8000/citizens/step/showWasteCollection

Fast-server

First make sure you are connected to the VPN, then log into the server with the provided credentials.

Apache config

The Apache server must now be configured to map the port the new server will be running on onto a new api endpoint. A new location entry needs to be added to /etc/apache2/sites-enabled/fast-api.conf that specifies both these values.

Open the file:

$ vi /etc/apache2/sites-enabled/fast-api.conf

There will already be numerous entries taking the following form:

<Location /api/v7>
ProxyPass http://127.0.0.1:8087
ProxyPassReverse http://127.0.0.1:8087
</Location>

Look for the one with the highest version number, (the 7 in <Location /api/v7> in this case). This number incremented by one (v7 -> v8), as well as the port number incremented by one (8087 -> 8088) will be used for the new endpoint. Make sure the new version number and the new port number aren't in use anywhere else in the file.

Now add the following lines under the last <Location /api/vY>... entry:

<Location /api/vX>
ProxyPass http://127.0.0.1:PORT
ProxyPassReverse http://127.0.0.1:PORT
</Location>

Where ofcourse X stands for the incremented api version and PORT for the incremented port number.

Lastly reload the apache config file:

$ /etc/init.d/apache2 reload

Run in docker

The image is not published yet, so first build it:

docker build --tag fastserver:0.1 .

and then:

docker run --name=fast_server -d -p 8000:8000 fastserver:0.1

Server config

Clone your version of the repository into a new folder inside the ~/repos/ folder and install the npm packages.

Seeing as there already exists a 'server' folder, continue the trend and name it version-X (keeping in line with the value used in the apache config) e.g.:

$ git clone https://gitlab.ilabt.imec.be/fast-icon/server.git --branch YOURBRANCH version-X
$ cd version-X
$ npm install

Before we can run the server the following two lines at the top of the config file (config.js) need to be adjusted to reflect the values chosen in the apache config:

...
const port = 'PORT';
const routesPrefix = '/api/vX/'
// this should already be pointing to the right script but check anyways
const eyePath = "/opt/eye/bin/eye.sh" 
...

Lastly we need to create a new screen session to run the server in:

$ screen -R api-vX # once again using the aformentioned version number instead of X

Start the server inside the screen session:

$ npm start

Now detach screen from the terminal by pressing C-a C-D (Control-A Control-D). Make sure not to use C-c or C-d to exit the session as this will kill the server.

Listing active screen session can be done using $ screen -ls. Reattaching to the screen session of a server is achieved by running $ screen -R api-vX again.