IPSM Docker deployment

Docker deployment of the Inter-Platform Semantic Mediator (IPSM) uses Docker Compose tool and consists of the following Docker images:

• wurstmeister/zookeeper
• wurstmeister/kafka
• interiot/ipsm-core

Content of the repository

Repository contains the following files and folders

• kafka-scripts – initialization script for the Apache Kafka container
• docker-compose.yml – definition of the IPSM deployment (to be used with Docker Compose)
• config.env – configuration file
• configure.sh – configuration script
• README.md – this file

Installation process

The IPSM deployment requires a working Docker installation. The deployment process has been tested using Docker (version 17.09.0-ce) and Docker Compose (version 1.17.0). It is advisable to install both tools manually and not rely on versions found in third-party repositories, as they tend to be outdated.

SSL setup

The deployment requires a working SSL setup for Apache Kafka server and client(s). Such a setup (utilizing self-signed certificates) can be generated by cloning the ipsm-ssl repository

git clone https://github.com/INTER-IoT/ipsm-ssl.git

and following instructions provided in its README.md file.

Cloning the repository

Assuming that the SSL setup has been created, in the next step you need to clone the main IPSM Docker deployment git repository.

git clone https://github.com/INTER-IoT/ipsm-docker.git
cd ipsm-docker

Environment variables

The config.env configuration file, located in the main folder of the repository, defines three environment variables:

• SSL_CONFIG – should point to the main directory of the (properly configured) copy of the ipsm-ssl repository,
• IPSM_HOST – the default 10.0.2.15 IP address should be changed to the IP address of the IPSM deployment machine (don't use localhost nor 127.0.0.1),
• IPSM_PORT – defines the port number for the IPSM REST service (can be left as is)

Configuration script

To finish the deployment configuration process invoke the command

bash ./configure.sh

Finally, to retrieve all needed images, create and start containers execute the following command.

docker-compose up -d

Upon the first startup IPSM will fail with log messages (see Accessing logs below) similar to:

ipsm_1  | hh:mm:ss – ERROR eu.interiot.ipsm.core.Main$ – DB initialization failed: null
ipsm_1  | hh:mm:ss – ERROR eu.interiot.ipsm.core.Main$ – Shutting down IPSM

There is nothing to worry about, though. IPSM uses SQLite for persisting its internal data (alignments and channel configurations) and upon the first startup the necessary file is not present. It gest created and IPSM accesses it just fine upon its automatic restart. The only downside is a small delay caused by the restart. Fortunately, it should only happen at the first startup.

To make sure that everything went as expected use your browser to access the IPSM REST API swagger interface. Both swagger interface and the IPSM REST API are by default available on port 8888.

Accessing logs

Logs of any of the IPSM deployment components can be accessed via docker-compose. You need to be in the main directory of the cloned repository (i.e., the one containing the docker-compose.yml file). To see the logs for a specific container issue the command

docker-compose logs container-name

where "container-name" is one of: zookeeper, kafka, and ipsm. If you want to inspect, for example, just 100 most recent lines of the ipsm logfile, use the --tail option as follows:

docker-compose logs --tail="100" ipsm

Clean re-install

Caution! Before performing the re-install you might want to create a backup copy of the configuration settings (contained in the config.env file) that you might have changed:

cp config.env config.env.bak

To perform a clean reinstall of the IPSM you need to

a) stop the IPSM

docker-compose down

b) possibly pull any updates available at the IPSM deployment repo

git checkout .
git pull

c) possibly restore your configuration settings:

cp config.env.bak config.env

d) repeat the steps described in the Installation process section (skip cloning the repository, of course)

Converting legacy alignments into currently supported format

The legacy pure-XML alignment format (supported by IPSM up to ver. 0.5.4.2) has been deprecated and is not supported by current IPSM deployments. Since ver. 0.8.8, the IPSM REST-API offers two services, which can convert the legacy alignments into the current format:

• /convert – consumes a legacy (pure-XML) alignment and returns its RDF/XML version

• /convert/TTL – consumes alignment in RDF/XML and outputs its alternative version, in which all cells use Turtle instead of the (considerably less readable) RDF/XML.