Starting a full Karabo system all local

Here we describe how you can bring up a basic Karabo system on a single host. Make sure you have understood the fundamental concepts before proceeding here.

Lets go step by step. The only prerequisit is, that you have installed and activated Karabo as described here.

Step 1: Local Message Broker

The first thing that must run for Karabo to work is the message broker. If you are in the European XFEL GmbH network you can use our always running broker (tcp://exfl-broker:7777) and skip to the next step. If you are outside of the European XFEL network you must start the broker locally on your computer. To accomplish this type:

karabo-startbroker

This will start the broker as a background process. It will be reachable under tcp://localhost:7777 from now on.

To stop the broker simply type:

karabo-stopbroker

Step 2: Edit the run file of the ProjectManager

Starting with Karabo 2.11, you can use a Local Project Database backed by the local filesystem, dropping the requirement for an existDB server.

To use the new filesystem backed Project Database, open the run file in var/service/karabo_projectDBServer, here remove or comment out the lines referring to existDB and uncomment the line after a file-based backend ... below:.

If you wish to use a local existDB server or are using a karabo version earlier than 2.11, follow the instructions listed here.

Step 3: Edit the environment files

In the karabo folder navigate to var/environment and set the content file named KARABO_BROKER to tcp://localhost:7777 and the content of the file named KARABO_PROJECT_DB to localhost

Step 4: Start the karabo backbone

Now you can start an “empty” Karabo by typing:

karabo-start

and stop it with:

karabo-stop

If you succeeded up to now you are ready to start additional servers, develop you own device plugins etc.

Local ExistDB Project Database

Since version 2.6 the Karabo binaries are not shipped with the code necessary to run the Configuration Database itself. The consequence of this choice is that a completely local system must be able to run docker containers as the user running Karabo.

This is either achieved by having the Karabo user added to the group docker or by installing docker in rootless mode (which is deemed more secure and available as an experimental feature since version 19.03 of the docker engine).

The complexity of how to install docker on any target system exceeds the scope of this documentation. Assuming one has the target system set up correctly, to start a local database, one needs to run by typing:

karabo-startprojectdb

To stop the database type:

karabo-stopprojectdb

The karabo-startprojectdb will attempt to pull the docker image europeanxfel/existdb:2.2 from hub.docker.com. In case the all local system is isolated from the internet, one needs to provide the image either by connecting the host temporarily to the internet, or by using the docker save and docker load commands.

The DB’s data resides in the container and will be archived at 00 and 12 hours by default. The data saved with such a procedure, is saved in the var/data/exist_data folder. While the runtime data is stored in the container storage. To wipe the memory, one needs to remove the container using the docker rm command, i.e. stopping the container with karabo-stopprojectdb and running docker rm karabo_existdb.

In case one wishes to change the main username and password for the database, one should follow the instructions in the README.md of the source of the image, and update the content of the KARABO_PROJECT_DB_USER and KARABO_PROJECT_DB_PASSWORD accordingly.