AWARE Micro

This is the new AWARE server for conducting studies using AWARE. It is a reactive, non-blocking server able to handle thousands of requests per second on a single machine.

This can be run on any OS as it is a JVM server implementation. This server is built using . It is compatible with the existing AWARE clients.

This is not compatible with the old dashboard located at api.awareframework.com. We are working on a new front-end to interface with AWARE Micro deployments.

Keep in mind the following troubleshooting:

• Check the firewall open ports if you can’t reach your aware-micro http://host:8080 address on your browser. You need port 8080 open.

• Your MySQL configuration can’t use root as a user. The root user is special and only allows local connections and root privileges to connect to MySQL. JVM doesn’t run with root permissions so this won’t work. Create a new user, with all permissions on the study-specific database.

Deploying server

The only dependency you need on your server is having Java (OpenJDK 11) installed.

For Debian/Ubuntu:

sudo apt install openjdk-11-jdk

For CentOS/Fedora:

sudo dnf install java-11-openjdk-devel

Set the default Java compiler to the latest JDK and choose the JDK, not JRE.

Debian/Ubuntu

sudo update-alternatives --config java

CentOS/Fedora

sudo alternatives --config java

Getting the server code

Make sure you have Git installed on your server:

For Debian/Ubuntu:

sudo apt install git

For CentOS/Fedora:

sudo dnf install git

Check out the latest source code of the server

git clone https://github.com/denzilferreira/aware-micro.git

Running the server with support for runtime study configuration changes

cd aware-micro
./gradlew clean build run

The first time you run this, it will cache the settings from the client and all the plugins into an aware-config.json. Once you stop seeing cached messages, you can stop the server using CTRL+C. You can edit the aware-config.json file to configure the database, SSL certificates, ports, and sensor & plugin settings for your study.

Deploy the study (dynamic configuration)

Once you are happy with the configuration, you can keep your server active by creating a screen and running the instance inside that screen.

screen
./gradlew run

If you open a new terminal and edit the aware-config.json file, the changes are applied immediately on the server. The clients will retrieve the new configuration after 15 minutes.

Running the server that won’t change study configuration half-way

cd aware-micro
./gradlew clean build shadowJar

This will build and create .jar file in build/libs. Change to this directory and run the server for the first time:

cd build/libs
java -jar micro-1.0.0-SNAPSHOT-fat.jar

This will create a file aware-config.json. Press CTRL+C to stop your server. You can edit this file to configure what database will be used and port, encryption and sensor & plugin settings for your study.

Deploy the study (static configuration)

Once you are happy with the configuration, you can keep your server active by creating a screen and running the instance inside that screen.

screen
java -jar micro-1.0.0-SNAPSHOT-fat.jar

Securing your server with LetsEncrypt

Depending on the OS you have, follow the instructions from: https://certbot.eff.org/.

In the question: My HTTP website is running <Software, choose None of the above> on <System, pick your OS> and follow the instructions to get fullchain.pem and privkey.pem files for your domain. Once you have these two files, set the following permissions so that Gradle can read them and use them on your server:

chmod 770 PATH_TO/fullchain.pem
chmod 770 PATH_TO/privkey.pem

You can now edit aware-config.json to point to these two files by setting the variables:

path_fullchain_pem = "PATH_TO/fullchain.pem"
path_key_pem = "PATH_TO/privkey.pem"

Update the server_host to have https:// in the URL and start your server. If you open your URL, the connection will be encrypted.

Deploy your AWARE Micro server with Docker

Docker is a platform for developing, shipping, and running applications. By using Docker, you can quickly deploy your server to AWS, GCP, and Azure and scale up. Once you have your study configured locally on your machine, you can ship the configuration and compiled server to a Docker instance.

Please set up Docker into your environment first. You can see how to set Docker on each environment here.

1. For making a container of your server, you need to prepare aware-config.json and micro-1.0.0-SNAPSHOT-fat.jar at a same directory.

2. At the same directory, please make a Dockerfile like below.

FROM openjdk:11

# Set the location of the verticles
ENV VERTICLE_HOME /usr/verticles

# Set the name of the verticle to deploy
ENV VERTICLE_AWARE_JAR micro-1.0.0-SNAPSHOT-fat.jar
ENV VERTICLE_AWARE_CONFIG aware-config.json

EXPOSE 8080

# Set vertx option
ENV VERTX_OPTIONS ""

# Copy your verticle and configuration to the container
COPY $VERTICLE_AWARE_JAR $VERTICLE_HOME/
COPY $VERTICLE_AWARE_CONFIG $VERTICLE_HOME/

WORKDIR $VERTICLE_HOME
ENTRYPOINT ["sh", "-c"]
CMD ["exec java -jar $VERTICLE_AWARE_JAR"]

1. You can build the container and make an image of the server by the following command:

docker build -t aware/micro .

1. For running the server image, you can use the docker run command.

docker run -i -t -p 8080:8080 aware/micro

Please modify the port number with your environment. You can get more information about running Vert.x on Docker here.