Setting up your own openEASE server

This page collects information on the installation and usage of openEASE, a web-service based on Docker. Using Docker, we have created a cloud-based infrastructure for providing KnowRob as a service via the Web. You can follow the steps described here for any Ubuntu version that has docker independently of the Ubuntu version running inside of openEASE.

Firefox is by far the most tested browser. Packages in ubuntu repositories should work with KnowRob. If you don't already have firefox installed, you can do so by calling:

sudo apt-get install firefox

Alternatively, you can use the Chromium Web-Browser.

When the Browser is installed check that WebGL is supported.

Install Docker following the instructions at https://docs.docker.com/engine/installation/linux/ubuntulinux/.

After installation, you need to log out and log in again to have your username added to the new group 'docker'.

In addition, you will need to install docker-compose which is used for the orchestration of the openEASE application. Install instrucitons for docker-compose can be found here: https://docs.docker.com/compose/install/

The next step is to clone the openEASE repository:

git clone https://github.com/ease-crc/openease.git

Clients can communicate with the openEASE webserver using SSL encryption. For local testing you can generate a certificate with following commands:

cd ./openease/certs/
./gencert.sh

NOTE: Please consider using a trusted certificate when running a production server, browsers will complain about the generated certificate!

NOTE: this is subject of change, experiment logs will be inserted differently soon (DB 08/19)

Experiment logs can be downloaded via a public FTP server that is hosted in the network of the university of Bremen. The server can be accessed via following URL: ftp://open-ease-stor.informatik.uni-bremen.de. The openEASE server requires experiments to be available in the local filesystem. In order to download all experiments, you can use following commands:

wget --mirror --no-host-directories -P episodes ftp://open-ease-stor.informatik.uni-bremen.de

Finally, the server needs to know where the episodes are located in the local filesystem. This is done using an environment variable. Add following line to your .bash.rc and replace $PATH_TO_DOCKER with the corresponding path in your filesystem:

export OPENEASE_EPISODE_DATA="$PATH_TO_DOCKER/docker/episodes/"

This directory is exposed to docker as data volume. The corresponding data volume container is called episode_data. Make sure the old data volume is deleted after modifying the episode path:

docker rm -f episode_data

The volume container is automatically created based on the environment variable next time you start the openEASE webserver.

The admin user is automatically created when the webserver starts for the first time. The default password is 1234. You can change it after logging in for the first time.

openEASE depends on rosjava. There are ubuntu packages available for ROS hydro and indigo. indigo is used by default, but you can change the ROS distribution by extending your environment:

export OPENEASE_ROS_DISTRIBUTION="kinetic"

NOTE: this is subject of change, meshes will be part of episodic memory soon (DB 08/19)

Meshes can be downloaded from custom git or svn repositories. This information must be included in the environment, for example:

export OPENEASE_MESHES="svn http://svn.ai.uni-bremen.de/svn/cad_models"
export OPENEASE_MESHES="git https://github.com/code-iai/iai_maps,$OPENEASE_MESHES"
export OPENEASE_MESHES="git https://github.com/code-iai/iai_robots,$OPENEASE_MESHES"
export OPENEASE_MESHES="git https://github.com/daniel86/pr2_common,$OPENEASE_MESHES"

openEASE allows you to sign in via oAuth. You have to register the openEASE app and acquire authentication and secret token from the service. This information must be included in the environment:

export GITHUB_APP_ID "XXX"
export GITHUB_APP_SECRET "XXX"
export GOOGLE_APP_ID "XXX"
export GOOGLE_APP_SECRET "XXX"
export FACEBOOK_APP_ID "XXX"
export FACEBOOK_APP_SECRET "XXX"
export TWITTER_APP_ID "XXX"
export TWITTER_APP_SECRET "XXX"

For production servers, you might want a working password recovery mechanism. This requires a mail account that is used for sending the recovery mails. Add two more environment variables to the .bash.rc:

export OPENEASE_MAIL_USERNAME="XXX@gmail.com"
export OPENEASE_MAIL_PASSWORD="XXX"

openEASE uses docker-compose. You can run openEASE by changing into the 'openease' folder and then running:

docker-compose up

Then you can connect to the Web interface at https://localhost.

Mongo dumps are included in the episode data downloaded from the FTP. This data can be imported into the mongo server using the administration interface of the website. Log in as admin user and select “Admin/Mongo/Synchronization” in the menu bar at the top of the page. A table with a row for each experiment is shown then. Press the “Import” button in the right most column in order to import the mongo logs for one of the experiments.

NOTE: this is not supported as of 08/19, but the feature will be added again at a later time

openEASE is a webapp and thus components may require active internet connection. We try to keep our code offline compatible but since external libraries are used, we can't ensure that all features are working without Internet connection. We provide a special start script that – additionally – starts a dummy DNS server in order to avoid timeouts when requesting DNS with no active Internet connection (the dummy DNS server maps all domains to localhost).

Without active Internet connection, execute following call instead of calling 'start-webrob'

./scripts/start-webrob-offline

Get a bash console in the postgres container

docker exec -it postgres_db bash

Start psql session for docker user

psql --username=docker

Write SQL statements, e.g., add a column in the user table

ALTER TABLE public.user ADD column_name character varying(50) NOT NULL DEFAULT '';

Or update text of the tutorial table (Note the E in the beginning of the string)

UPDATE tutorial SET text=E'The user interface consists of six panes with different purposes.\n....' WHERE id=220;

You may run into permission problems when accessing /var/run/docker.sock. This is due to an assumption that the docker group id is 999. In order to solve this problem you can:

• Manually change the group ID to 999 (preferred)
• Allow everyone to access docker.sock by executing following command: chmod ugo+rw /var/run/docker.sock

Launching the start-webrob script may yield in following error:

No mongo_db container exists, creating a new one...
7c67110c30f9350040298467ceaf5ab5acdf90a3ba39ad90f03934ff177c0846
FATA[0000] Error response from daemon: Cannot start container 
7c67110c30f9350040298467ceaf5ab5acdf90a3ba39ad90f03934ff177c0846: Error 
starting userland proxy: listen tcp 0.0.0.0:27017: bind: address already in use

This indicates that there is a mongo server running on the host machine. With Ubuntu, you can stop the server by executing following command:

sudo service mongodb stop

In some situations it may help to start again with a clean docker installation. This requires removing all containers and images. You can do that using following commands:

docker rm $(docker ps -a -q)
docker rmi $(docker images -q)

After that is done you have to begin from the start of this tutorial page again.