Installation Guide Part 1

Platform Installation and Configuration

This page covers the undimmed parts of the flow.

Grocery

Note the vocabulary we use throughout this documentation:

• Server machine: A server is a software program that receives requests and respond to callers properly. For consistency, the term server machine is used to indicate a computing system (whether it is a virtual machine or a physical computer) where you install the OmniTrack backend server and which is persistently running with network connection.

• Terminal (Command-line): a terminal is a text-based interface that allows to interact with system-level commands without GUI. Because the server machine is likely to exist remotely, you would mostly handle the server machine through a terminal emulator on your work computer. If your work computer is Windows, you can use putty or PowerShell. On MacOS, you can use the Terminal app, which is installed by default in Applications/utilities. You can access your server machine via SSH in terminal.

• OS (Operating System): OS is a system software what you interact with to install and use other programs. Windows, MacOS, Linux, iOS, Android are all operating systems.

Step 1 - Prepare a server machine with a public IP

※The OmniTrack backend server can run on various operating systems including Windows, MacOS, and Ubuntu Linux. If you are not debugging the server, you should probably choose Ubuntu Linux. Therefore, the rest of this page assumes that you are using Ubuntu.

• As a server machine, there are several choices you can choose:

  Option 1: Use your own facility (desktop or server computer) connected to the internet
  You can run the server on your own computer or one provided by your institute. However, make sure that you can keep the machine turned on 24/7, and the machine has a publicly available IP address.

  Option 2: Use a commercial cloud computing platform
  You can use commercial cloud computing platforms which provide a server instance that can be accessed remotely.

  1. Microsoft Azure (https://azure.microsoft.com/services/virtual-machines/linux-and-open/)
     Refer to our guide for setting the Azure virtual machine.

  2. Amazon AWS (https://aws.amazon.com/ec2/)

  3. Google Cloud Platform (https://cloud.google.com/compute/)

  4. DigitalOcean (https://www.digitalocean.com)

  • Recommended system specification

    RAM	>= 4Gb
    HDD/SSD	>= 20Gb
    OS	>= Ubuntu Linux 14.08 LTS

• Make sure the ports are permitted to be accessed from outside:

  Usage	Port
  OmniTrack backend server (Node.js)	3000
  Research dashboard (Angular)	80 is used by default, but you can use any arbitrary port if you cannot get approval to open the port 80.

• (Optional) We strongly recommend encrypting the communication using HTTPS, because your server will receive critical credential information of researchers and study participants.
  There are popular services that provide free HTTPS certificate, such as LetsEncrypt (https://letsencrypt.org/).

---

The rest of the steps assume that you are on the terminal that handles the server machine. Each line starting with > indicates a line of command you have to type in and press the enter key. Note that you don't type '>'.

> command arg1 arg2 arg3... [press enter]
> command arg1 arg2 arg3... [press enter]

To connect to your server machine via SSH, use this command in a terminal on your work computer:

> ssh [YOUR_USERNAME]@[SERVER_IP]

Replace [YOUR_USERNAME] and [SERVER_IP]. Do not include the brackets. For example:

> ssh yhkim@123.45.67.8

Then the terminal will prompt you for the password for the server. Type in the password and press the enter key (Mostly, you don't receive feedback on the password typing).

---

Step 2 - Install platform dependencies on the server

2-1. MongoDB - Install the latest version of MongoDB community edition (Snippet from the official guide).

Installing MongoDB 3.6 on Ubuntu >=16.04 (Works on 18.x)

> sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv 2930ADAE8CAF5059EE73BB4B58712A2291FA4AD5
> echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu xenial/mongodb-org/3.6 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-3.6.list
> sudo apt-get update
> sudo apt-get install -y mongodb-org

Then, run MongoDB service:

> sudo service mongod start

Also, register MongoDB to restart on reboot:

> sudo systemctl enable mongod.service
> sudo systemctl start mongod

2-2. Node.js - Install Node.js (Snippet from the official guide)

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

Make sure you are using the latest version of NPM (Node Package Manager)

> sudo npm i -g npm

---

Step 3 - Setup the OmniTrack backend and frontend web server

3-1. Go to home directory.

> cd ~/

3-2. Clone the source code into your server machine.

> git clone https://github.com/muclipse/omnitrack_backend_server
> cd omnitrack_backend_server

3-3. Run setup in the repository directory.

> sh ./_setup-ubuntu.sh

To build mobile apps with the research dashboard, setup an Android SDK on the server.

> sh ./_setup-android-sdk-ubuntu.sh

During the process, the console may ask you to choose one of the Java development kit version from the installed list. Insert the index of Java 8.

Finally, run source command as the prompt says:

> source ~/.bashrc

3-4. Install Node dependencies.

> npm install

---

Step 4 - Run the OmniTrack backend server

Along with the frontend web server, you should keep the backend server running. (e.g., automatically restart when the machine is rebooted.)

The backend server is a Node.js app built with Express.js, which officially provides several ways (Forever.js, PM2, and SystemD) to keep the server alive.

Here we provide a guide to setup PM2.

4-1. Make sure the MongoDB server is running in background.

> sudo service mongod status

If the console does NOT print Active: active (running) since, start mongod manually.

> sudo service mongod start

4-2. Install PM2 using NPM.

> sudo npm i -g pm2

4-3. Run this command to start (or restart) a daemon.

> npm run backend-pm2

4-4. If a daemon successfully started, you should see something like this:

---

Step 5 - Run the frontend web server for research dashboard

Run the shell script in the repository directory:

> sh _refresh-frontend-release.sh

Your directory path to publish the frontend is /home/YOUR_USERNAME/omnitrack_backend_server/dist/public

This is a set of pure HTML, CSS, and Javascript file which can be published via diverse web servers.

Setup an HTTP server on the system to publish the code in /dist via 80 port.

Our official way is using Apache.

Installing Apache2 on Ubuntu (Snippets from the official guide)

  > sudo apt-get update
  > sudo apt-get install apache2

In the ordinary cases, you will configure your server in /etc/apache2/sites-available/000-default.conf

To edit the file:

> vi /etc/apache2/sites-available/000-default.conf

Overwrite the virtualhost. Replace all the [DIRECTORY_PATH] with your frontend directory path:
for example, assuming that YOUR_USERNAME is yhkim,

DocumentRoot [DIRECTORY_PATH]_ => DocumentRoot /home/yhkim/omnitrack_backend_server/dist/public

<Directory [DIRECTORY_PATH]> => <Directory /home/yhkim/omnitrack_backend_server/dist/public>

If you cannot open the port 80, use another one.

<VirtualHost *:80>
  ServerAdmin webmaster@localhost
  DocumentRoot [DIRECTORY_PATH]

  <Directory [DIRECTORY_PATH]>
    AllowOverride all
    Allow from all
    Require all granted
    RewriteEngine On
    RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -f [OR]
    RewriteCond %{DOCUMENT_ROOT}%{REQUEST_URI} -d
    RewriteRule ^ - [L]
    
    RewriteCond %{REQUEST_URI} !^/auth/(.*)$
    RewriteCond %{REQUEST_URI} !^/api/(.*)$
    RewriteRule ^ /index.html
  </Directory>
  ProxyPass /api http://localhost:3000/api
</VirtualHost>

Reload apache2 to apply changes:

> sudo a2enmod rewrite && sudo a2enmod proxy && sudo a2enmod proxy_http
> service apache2 reload

---

Next: Part 2: Configuring Firebase