Installation of development version

Here's a brief overview of the installation process for development purposes.

Prerequisites

It is assumed that Java 8 or higher is installed. Other than that, there are no mandatory external dependencies.

I. Fresh install

1) Install Postgresql 10.x and pgAdmin GUI tool

Visit https://www.postgresql.org/download/ and download a binary package for your OS. Depending on OS/package and actions, taken during the installation process, installed Postgresql instance will be configured to run automatically or manually. If the database does not run automatically (which you may check by looking for port 5432 in the list of open TCP ports), then take a look in data/logs/pg10/install.log. It contains a command for running the database manually.

pgAdmin's purpose is browsing and administering a Postgresql instance within a convenient GUI. It's a separate application, which is usually installed from the same package as Postgresql itself.

2) Configure the database

Each Octopus instance requires a separate database schema. By default, Octopus assumes that the database JDBC url is as follows: jdbc:postgresql://localhost:5432/octopus?currentSchema=octopus and credentials are postgres:postgres, i.e. (1) Postgresql is running on the same host as Octopus on (default) port 5432, (2) there is a database named octopus, (3) there is a schema named octopus inside the octopus database, (4) both database and schema are owned by user postgres (with password same as username).

This means that what you need to do is:

• launch pgAdmin and connect to Postgresql instance at localhost:5432
• check if postgres user exists; if not, create:

CREATE ROLE postgres LOGIN
  ENCRYPTED PASSWORD 'md53175bce1d3201d16594cebf9d7eb3f9d'
  SUPERUSER INHERIT CREATEDB CREATEROLE REPLICATION;

• create database octopus:

CREATE DATABASE octopus
  WITH OWNER = postgres
       ENCODING = 'UTF8'
       TABLESPACE = pg_default
       LC_COLLATE = 'C'
       LC_CTYPE = 'C'
       CONNECTION LIMIT = -1;

• create schema octopus:

CREATE SCHEMA octopus
  AUTHORIZATION postgres;

3) Clone Octopus git repo

$ git clone https://github.com/manaty/octopus.git

4) Build artifacts

$ ./gradlew build -x test

5) Initialize the database schema by using Liquibase module

Navigate to the repository's root directory and run the following command (replacing <version> placeholder with proper value, which depends on current version of the project; you may look for it in build.gradle file):

$ java -jar db/build/libs/db-<version>-all.jar --config=db/config/db-dev.yml --lb-update --lb-default-schema=octopus

Check the logs for any errors. You may also refresh the schema in pgAdmin to see, if new tables have been created.

6) Launch the server

From the repository's root directory run the following command (replacing <report-output-directory> and <version> placeholders with proper values):

$ java -Dbq.server.reportRoot=<report-output-directory> -jar server/build/libs/server-<version>-all.jar --config=server/config/server-dev.yml --octopus-server

If Emotiv PRO software is not installed (or not running), you will see an error log message like this:

[24/May/2019:11:52:26] vert.x-eventloop-thread-2 ERROR n.m.o.s.e.CortexClientImpl: Failed to connect websocket
io.netty.channel.AbstractChannel$AnnotatedConnectException: Connection refused: localhost/127.0.0.1:54321
	at sun.nio.ch.SocketChannelImpl.checkConnect(Native Method)
	at sun.nio.ch.SocketChannelImpl.finishConnect(SocketChannelImpl.java:717)
	at io.netty.channel.socket.nio.NioSocketChannel.doFinishConnect(NioSocketChannel.java:327)
	at io.netty.channel.nio.AbstractNioChannel$AbstractNioUnsafe.finishConnect(AbstractNioChannel.java:340)
	at io.netty.channel.nio.NioEventLoop.processSelectedKey(NioEventLoop.java:644)
	at io.netty.channel.nio.NioEventLoop.processSelectedKeysOptimized(NioEventLoop.java:591)
	at io.netty.channel.nio.NioEventLoop.processSelectedKeys(NioEventLoop.java:508)
	at io.netty.channel.nio.NioEventLoop.run(NioEventLoop.java:470)
	at io.netty.util.concurrent.SingleThreadEventExecutor$5.run(SingleThreadEventExecutor.java:909)
	at io.netty.util.concurrent.FastThreadLocalRunnable.run(FastThreadLocalRunnable.java:30)
	at java.lang.Thread.run(Thread.java:748)
Caused by: java.net.ConnectException: Connection refused
	... 11 common frames omitted

If you see it, don't freak out, as it's perfectly fine. Other parts of Octopus like Client API and Web API will function properly, even if Emotiv server is unavailable.

II. Updating the git project to latest revision (or switching to different revision)

When you switch to a different git revision (either by pulling new changes or switching to a branch or checking out an earlier commit), there's a risk that the structure of Octopus schema, that already exists in your database, is incompatible with the new revision. To mitigate possible startup and runtime problems (which might not always be obvious), make sure to run the following commands:

1. First, re-build the artifacts:

$ ./gradlew build -x test

2. Second, drop all objects from the database schema by using Liquibase:

$ java -jar db/build/libs/db-<version>-all.jar --config=db/config/db-dev.yml --lb-drop-all --lb-default-schema=octopus

3. Finally, initialize the database schema from scratch as in step I.5:

$ java -jar db/build/libs/db-<version>-all.jar --config=db/config/db-dev.yml --lb-update --lb-default-schema=octopus