Skip to content

Installation of development version

Jump to bottom
Andrei Tomashpolskiy edited this page May 24, 2019 · 9 revisions

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
  1. 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
  1. 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

III. Running multiple Octopus servers on the same host

This is a situation, when you as a developer want to check interop between two Octopus instances, but don't have the possibility or desire to setup VMs or different machines.

1) Decide, if you are concerned about 100% correctness of data in the reports

Two Octopus instances may use a single database schema and operate just fine (in the sense, that data consistency is currently not compromised, as there are no updates and no FKs or logical correlations between different records).

1.1) If yes, create a separate schema for each Octopus instance

For instance, if you need to verify that the reports work correctly (especially, the time adjustment part), it may be a good idea to create a separate schema for each Octopus instance. The easiest way to do this would be to do steps I.2 and I.5 for each Octopus instance, and on each iteration change the schema name (e.g. append a unique number to the name, like octopus2, octopus3, etc.) Important thing to remember is that you also need to change one of the command line parameters to the Liquibase command. For instance, if the database schema name is octopus2, then instead of the default command you need to use the following (note that --lb-default-schema is changed):

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

2) Create copies of YML configuration

It's the easiest way to change the configuration: copy the server-dev.yml file with a different name (e.g. server-dev2.yml); then update the configuration values directly inside the new file.

Values that you'll need to update are:

  • grpc.port: default value is 9991, so pick a different one (e.g. 9992)
  • jetty.connectors[@type="http"].port: default value is 9998, so pick a different one (e.g. 9999)

Depending on what you decided in step 1, you may also need to update jdbc.octopus.url. Default value is jdbc:postgresql://localhost:5432/octopus?currentSchema=octopus; you need to change only the last parameter, e.g.: ?currentSchema=octopus2.

Values that you might want to update are:

  • grpc.master: it's an object node, which by default is absent, and this means that this is a master server; for slave servers you'll need to specify the master's address:
grpc:
  port: 9992
  master:
    address: localhost:9991

3) Run all instances

Similar to I.6, but you need to use a different config for each Octopus instance being run, e.g.:

# Run master instance (assuming that server-dev.yml is master's config)
$ java -Dbq.server.reportRoot=<report-output-directory> -jar server/build/libs/server-<version>-all.jar --config=server/config/server-dev.yml --octopus-server

# Run slave instance (assuming that server-dev2.yml is slave's config with `grpc.master` pointing to master server)
$ java -Dbq.server.reportRoot=<report-output-directory> -jar server/build/libs/server-<version>-all.jar --config=server/config/server-dev2.yml --octopus-server

The order, in which you launch Octopus instances, does not matter; slaves continuously reconnect to masters, so launching master after slave or restarting any server at any time is fine.

Clone this wiki locally