aware-server

AWARE Server (to use with upcoming AWARE 5.0)

This AWARE Server is used for coordinating studies and storing/retriving their data into/from a MySQL database. If you have not yet setup your MySQL server setup, you should do that before following this guideline here

Disclaimer: the current implementation and setup scripts assume you are installing this server on an Ubuntu-based server.

The AWARE Server exposes the following REST interface:

Endpoint	Request type	Description
/config	GET	Endpoint for fetching study configuration
/insert	POST	Endpoint for inserting data

For insert endpoint request need to be in JSON format and must include following fields: timestamp (Double), deviceId (String), data (JSON), tableName (String)

Example insert of data:

{
    "tableName": "RuuviTag",
    "deviceId": "'dd8a91f6-ca32-30e0-983c-8f309d653045'",
    "data": {
        "battery": 3019,
        "acceleration": 993.812859647127,
        "acceleration_x": -60,
        "temperature": 22.99,
        "pressure": 1008.7,
        "acceleration_z": 992,
        "acceleration_y": 0,
        "humidity": 23.5
    },
    "timestamp": 1525266608
}

Dependencies

• Node.js v6.11.4 +
• MySQL v5.7 +
• Docker v17.09.0 +
• Ubuntu Server 16.04 LTS +

Pre-requisit open firewall ports for standalone

• 443 (TCP) - Used to secure your server using HTTP(S) and by LetsEncrypt Certbot certificate renewal process
• 22 (TCP) - Used to access the server over SSH console. This is also used by clutered server setups

Pre-requisit open firewall ports for cluster setup node servers for Docker Swarm

• 22 (TCP) - Used by main server to replicate main server setup in cluster nodes
• 2376 (TCP) - Docker Swarm
• 2377 (TCP) - Docker Swarm
• 4789 (TCP) - Docker Swarm
• 7946 (TCP) - Docker Swarm

Installing NodeJS

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs

Retrieving latest AWARE Server

mkdir ~/server
cd ~/server
npm install aware-server

Deployment of AWARE Server

There are currently two options for running the server: standalone and cluster. In cluster, Docker Swarm is used for creating many instances to gain high availability and scalability capacity for a study. Standalone deployments are recommended for small-numbers of participants (< 100).

Cluster setup

cd ~/server/node_modules/aware-server
./setup.sh

Standalone setup

cd ~/server/node_modules/aware-server
./setup-local.sh

Configuring AWARE Server

Adding new study

In order to add new study to Docker swarm setup script should be run again and selecting option 2) Add study to existing Docker Swarm. Setup script will guide adding new study to Docker Swarm. Studies are run each in different ports and therefoore same port cannot be used again. Setup script will display ports used by Docker Swarm.

Adding new node

When using Docker Swarm setup there is option for adding new instances to Docker Swarm cluster. This can be done by running the setup script again and selecting option 3) Add new node to existing Swarm.

Create key by using ssh-keygen and use cat to field and copy contents of id_rsa.pub to clipboard:

ssh-keygen -t rsa -b 4096 -o -a 100
cat ~/.ssh/id_rsa.pub

Copy the contents of id_rsa.pub in clipboard to other machines you want to use:

nano ~/.ssh/authorized_keys

Let's encrypt certificates

Setup script will guide installing Let's encrypt certificates if this option is chosen. In order to renew certificates setup script must be run and selecting option 4) Renew certificates manually.

In order to add automatical certificates renewal option select option 5) Add automatical certificates renewal. This will add crontab for automatical certificates renewal.

In order to certificates to be used in Docker Swarm they need to be reloaded to Docker Swarm. This is currently todo. The containers must be restarted with new secrets in use.

Database engine support

In current project knex is used for database communication. Knex has support for several different databases but here we officially only support MySQL v5.7+

Authors

• Mikko Yliniemi - Initial work - mikkoyli
• Denzil Ferreira - Extended to integrate with AWARE 5.0 client and Analysis Dashboard

License

This project is licensed under the APACHE 2.0 License - see the LICENSE file for details