INTER-MW Installation Guide
INTER-MW is distributed as a Docker Image which is available in the Inter-IoT Docker registry. A deployment script is provided in the commons repository for deploying the INTER-MW using the Docker Compose tool.
Prerequisites
Prerequisites for the INTER-MW installation are:
- Docker and Docker Compose
- access to the commons repository
- access to the Inter-IoT Docker registry
docker.inter-iot.eu
Optional
It is best to limit the size of Docker's log files [more info] by adding the following lines to your daemon.json file:
{
"log-driver": "json-file",
"log-opts": {
"max-size": "10m"
}
}
This will limit the log file size to 10mb.
Installation
Login to the Inter-IoT Docker registry as described here to gain access:
docker login docker.inter-iot.eu
Clone the commons repository containing Docker Compose files for INTER-MW deployment:
git clone https://git.inter-iot.eu/Inter-IoT/commons
The commons repository provides two variants of INTER-MW installation:
- installing INTER-MW individually (
commons/intermw-deployment) - installing INTER-MW together with IPSM (
commons/intermw-ipsm-deployment)
Installing INTER-MW Individually
IPSM has to be installed separately in accordance with the IPSM installation guide.
Navigate to the commons/intermw-deployment directory and configure Compose variables in the .env file. Default values are:
INTERMW_VERSION=v2.2.2
INTERMW_REST_API_PORT=8080
INTERMW_CALLBACK_PORT=8980
RABBITMQ_PORT=5672
RABBITMQ_ADMIN_PORT=15672
RABBITMQ_USER=admin
RABBITMQ_PASS=admin
PARLIAMENT_PORT=8089
To deploy the Inter-MW, run the following command:
docker-compose up -d
Following services are created by Docker Compose:
| Service | Description |
|---|---|
intermw |
INTER-MW application |
rabbitmq |
RabbitMQ message broker |
parliament |
Parliament triple store |
Following Docker volumes are created for persisting the INTER-MW state after containers are terminated. The volumes are created only if they don't exist yet otherwise the content is preserved.
| Volume Name | Content |
|---|---|
<prefix>_intermw_config |
InterMW configuration files |
<prefix>_rabbitmq_data |
RabbitMQ data files |
<prefix>_parliament_data |
Parliament data files |
When deploying the INTER-MW for the first time (clean install), the intermw_config volume is created and INTER-MW configuration files packed in the intermw image are copied to the volume. Afterwards the configuration files in the volume are preserved and are not overwritten.
Following ports are exposed by services:
| Port | Service | Bound to host | Description |
|---|---|---|---|
| 8080 | intermw |
Yes | INTER-MW REST API |
| 8980 | intermw |
Yes | INTER-MW callback listener for bridges |
| 5672 | rabbitmq |
No | RabbitMQ |
| 15672 | rabbitmq |
Yes* | RabbitMQ Management web UI |
| 8089 | parliament |
Yes* | Parliament, Web UI |
* For testing purposes
Installing INTER-MW together with IPSM
Navigate to the commons/intermw-ipsm-deployment directory and configure Compose variables in the .env file. Default values are:
# INTER-MW
INTERMW_VERSION=v2.2.2
INTERMW_REST_API_PORT=8080
INTERMW_CALLBACK_PORT=8980
RABBITMQ_PORT=5672
RABBITMQ_ADMIN_PORT=15672
RABBITMQ_USER=admin
RABBITMQ_PASS=admin
PARLIAMENT_PORT=8089
# IPSM
IPSM_VERSION=0.8.5
IPSM_REST_API_PORT=8888
KAFKA_PORT=9092
ZOOKEEPER_PORT=2181
Perform IPSM pre-installation steps as described in IPSM installation guide. Especially, check the environment/kafka_vars.env configuration file and set the Kafka IP/hostname in KAFKA_ADVERTISED_HOSTNAME and KAFKA_ADVERTISED_LISTENERS variables to host machine IP address. You can leave default value 172.17.0.1 if deploying on a Linux host maachine. Afterwards execute the following command to create Docker volumes for the IPSM:
./initialize-volumes.sh
To deploy the INTER-MW + IPSM, run the following command:
docker-compose up -d
Following services are created by Docker Compose:
| Service | Description |
|---|---|
intermw |
INTER-MW application |
rabbitmq |
RabbitMQ message broker |
parliament |
Parliament triple store |
ipsm |
Inter-Platform Semantic Mediator |
kafka |
Apache Kafka |
zookeeper |
Apache ZooKeeper |
Following Docker volumes are created for persisting the INTER-MW state after containers are terminated. The volumes are created only if they don't exist yet otherwise the content is preserved.
| Volume Name | Content |
|---|---|
<prefix>_intermw_config |
InterMW configuration files |
<prefix>_rabbitmq_data |
RabbitMQ data files |
<prefix>_parliament_data |
Parliament data files |
When deploying the INTER-MW for the first time (clean install), the intermw_config volume is created and INTER-MW configuration files packed in the intermw image are copied to the volume. Afterwards the configuration files in the volume are preserved and are not overwritten.
IPSM requires following external Docker volumes which have to be created manually by running the initialize-volumes.sh script:
| Volume Name | Content |
|---|---|
kafka-data |
Apache Kafka data files |
kafka-certs |
Certificates for the Apache Kafka |
kafka-scripts |
Initialization script for the Apache Kafka |
ipsm-data |
IPSM data files |
ipsm-certs |
Certificates for the IPSM |
Following ports are exposed by services:
| Port | Service | Bound to host | Description |
|---|---|---|---|
| 8080 | intermw |
Yes | INTER-MW REST API |
| 8980 | intermw |
Yes | INTER-MW callback listener for bridges |
| 5672 | rabbitmq |
No | RabbitMQ |
| 15672 | rabbitmq |
Yes* | RabbitMQ Management web UI |
| 8089 | parliament |
Yes* | Parliament, Web UI |
| 8888 | ipsm |
Yes | IPSM REST API |
| 9092 | kafka |
Yes | Apache Kafka |
| 2181 | zookeeper |
Yes | Apache ZooKeeper |
* For testing purposes
Configuration
INTER-MW configuration files are stored in a mounted Docker volume named <prefix>_intermw_config. To get the physical location on the host machine (mount point), use the following command:
docker volume inspect <prefix>_intermw_config
Note: if there are problems accessing mounted volume <prefix>_intermw_config on a Windows host machine, you can access configuration files through intermw container by starting an interactive shell:
docker exec -it <intermw-container> bash
cd /etc/inter-iot/intermw
vi <file-name>
After configuration is changed, the intermw service has to be restarted to take effect:
docker-compose restart intermw
Parliament triple store configuration
The Parliament triple store instance needs to have geo spatial indexes created after the first run in order for INTER-MW to use it's geospatial queries. This can be done by going to:
http://localhost:8089/parliament/indexes.jsp
and clicking on the Create all link next to the Default graph entry.
Monitoring and Troubleshooting
In case of any problem, first check logs from INTER-MW services for any errors. Logs can be displayed using the following command:
docker-compose logs <service-name>
To display last N lines of logs, use the option --tail:
docker-compose logs --tail <N> <service-name>
To follow the log output, use option -f:
docker-compose logs -f <service-name>
INTER-MW log files can be also accessed directly in the Docker container. Start a shell session:
docker exec -it <intermw-container> bash
Log files are stored in /var/log/inter-iot/intermw/ directory. Log files are rotated, as defined in log4j2.xml configuration file.