no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


Previous revision
Next revision
—doc:docker [2019/08/16 12:39] – [Setting up your own openEASE server] daniel86
Line 1: Line 1:
 +====== Setting up your own openEASE server ======
  
 +This page collects information on the installation and usage of openEASE, a web-service based on [[http://www.docker.com|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.
 +
 +===== Installing web-browser with WebGL support ====
 +
 +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 [[https://get.webgl.org/|WebGL is supported]].
 +
 +===== Installing the docker daemon =====
 +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'.
 +
 +
 +
 +===== Installing openEASE =====
 +
 +The next step is to clone the openEASE repository:
 +  git clone https://github.com/ease-crc/openease.git
 +
 +
 +===== Setting up WebSocket authentication =====
 +
 +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!
 +
 +===== Setting up experiment logs =====
 +
 +**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.
 +
 +===== Setting up admin user =====
 +
 +The admin user is automatically created when the webserver starts for the first time.
 +The password is taken from an environment variable. Please add following environment variable to your .bashrc
 +and replace 'XXX' with your admin password:
 +  export OPENEASE_ADMIN_PASSWORD="XXX"
 +
 +After you added the export to the .bashrc make sure to log-out and log-in again
 +(e.g., by restarting the terminal).
 +
 +**//NOTE//**: No admin user will be created if this variable is undefined.
 +
 +
 +===== Selecting a ROS distribution =====
 +
 +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"
 +
 +===== Setting up mesh repositories =====
 +**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"
 +
 +===== Setting up remote login (optional) =====
 +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"
 +
 +===== Setting up password recovery (optional) =====
 +
 +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"
 +
 +===== Launching openEASE =====
 +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.
 +
 +===== Setting up mongo server =====
 +
 +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.
 +
 +
 +===== Offline openEASE =====
 +**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
 +
 +
 +
 +===== Administration =====
 +
 +==== PostgresDB ===
 +
 +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;
 +
 +===== Troubleshooting =====
 +
 +==== Permissions on /var/run/docker.sock ====
 +
 +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''
 +
 +==== mongo address already in use ====
 +
 +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
 +  
 +
 +==== Other docker problems ====
 +
 +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.