Link Search Menu Expand Document
Open Integration Hub

Local Installation Guide

linux Windows Mac

In addition to setting up the Open Integration Hub on a cloud infrastructure such as GCP it is also possible to setup a local version of the framework. Make sure to perform the following to set up a local version of the OIH within your own minikube:

Development Environments

Besides the basic installation guide found here, the OIH monorepo provides two possible setups for a development environment. They are found in the dev-tools/ folder in the monorepo.

  • The minikube instructions provides the ability to deploy each service from its public Docker image or using local source code served over NFS. It is activated using the setup.sh script in the folder. This script automates all the steps found here.
  • The docker-compose installation contains configuration files and helper scripts to run local services directly from Docker. It still relies on minikube to execute flows.

Requirements

Please make sure to clone the monorepo before you start.

Make sure that minikube is endowed with sufficient resources. We suggest at least:

  • 8GB of memory
  • 4 CPUs
If you're using Windows we suggest to use virtual box. In order to use it, Hyper-V must be disabled Enable/Disable Hyper-V on Windows 10. You may also have to enable virtualisation features in your BIOS.

Installation

Install Minikube

Make sure minikube is installed, configured, and started. The command for allocating sufficient resources is

minikube start --memory 8192 --cpus 4
The OIH Framework requires the ingress addon for kubernetes. This is not supported via Docker Bridge for Mac and Windows. Therefore, on these Operating Systems, minikube must be started with the flag `--vm=true`. More information can be found on the minikube Github page.

If you already have an installed minikube instance that is using the virtualbox driver you can do

minikube stop

and then

VBoxManage modifyvm "minikube" --memory 8192 --cpus 4

to adjust the resource limits before starting again.

In particular, ensure that its ingress module is enabled (minikube addons enable ingress). Also make sure that kubectl is configured to use minikube. To see if its correctly configured use

`kubectl config current-context
or
cluster info`

For further information about how to set up minikube, see here:

If you're using Docker for Desktop it overwrites the acutal kubectl version. This version is generally not compatible with minikube. There are two options to correct this:
  • Download the `kubectl.exe` from Install kubectl on Windows. Navigate to the docker directory (e.g. Program Files\Docker\Docker\resources\bin) andreplace the kubectl.exe in this folder with the one you just downloaded.
  • Use the "Edge" version of Docker Desktop. This can be done by installing the edge version of the application from the Docker Desktop site. If you already have Docker Desktop installed, you can switch to the Edge version from the Docker menu. Select Preferences > Command Line and then activate the Enable experimental features toggle. After selecting Apply & Restart, Docker will update versions. More information can be found here.

Basic Open Integration Hub Infrastructure Setup

Please make sure to clone the monorepo before you start. You will need the files in the dev-tools/minikube folder.

Set up the basic Open Integration Hub infrastructure. To do this, from the dev-tools/minikube directory, simply execute

kubectl apply -f ./1-Platform

This may take a while to finish. You can use minikube dashboard to check the status of the various deployments. Once they are all ready, you can proceed. If you would like to deploy any services from their local source code, you also need to setup the local volume

kubectl apply -f ./1.1-CodeVolume kubectl apply -f ./1.2-CodeClaim

Host Rules Setup

To actually reach the services, you need to add an entry in your hosts file for each service. You can retrieve the IP with minikube ip and need to create an entry for each host listed in the ingress.yaml file (e.g. iam.example.com). If you are using…

a Linux distribution, you can automate this by using this terminal command:

echo "$(minikube ip) app-directory.example.com iam.example.com skm.example.com flow-repository.example.com auditlog.example.com metadata.example.com component-repository.example.com dispatcher-service.example.com webhooks.example.com attachment-storage-service.example.com data-hub.example.com ils.example.com web-ui.example.com" | sudo tee -a /etc/hosts

a Windows distribution, you can find the host files under:

c:\windows\system32\etc\hosts
or
c:\windows\system32\drivers\etc\hosts

then add

your_minikube_ip app-directory.example.com
your_minikube_ip iam.example.com
your_minikube_ip skm.example.com
your_minikube_ip flow-repository.example.com
your_minikube_ip auditlog.example.com
your_minikube_ip dispatcher-service.example.com
your_minikube_ip metadata.example.com
your_minikube_ip component-repository.example.com
your_minikube_ip webhooks.example.com
your_minikube_ip attachment-storage-service.example.com
your_minikube_ip data-hub.example.com
your_minikube_ip ils.example.com
your_minikube_ip web-ui.example.com

Identity and Access Management Deployment

Deploy the OIH Identity and Access Management. To do so, simply execute kubectl apply -f ./2-IAM. Again, wait until the service is fully deployed and ready.

Service Account Creation

Create a service account and token for the other services in the IAM. Using Postman (or another similar tool of choice), send these POST requests to the IAM.

Base URL: iam.example.com

Header: Content-Type: application/json:

Login as Admin

Path:

/login

Request Body:

{
  "username": "admin@openintegrationhub.com",
  "password": "somestring"
}

Response Body Structure:

{
  "token": "string"
}

Use the returned token as a Bearer token for the remaining requests.

Create a Service Account

Path:

/api/v1/users

Request Body:

{
  "username": "test@test.de",
  "firstname": "a",
  "lastname": "b",
  "role": "SERVICE_ACCOUNT",
  "status": "ACTIVE",
  "password": "asd",
  "permissions": ["all"]
}

Response Body Structure:

{
  "id": "string",
  "username": "string",
  "firstname": "string",
  "lastname": "string",
  "status": "active",
  "tenant": "string",
  "roles": [
    {
      "name": "string",
      "permissions": ["all"],
      "scope": "string"
    }
  ],
  "permissions": ["all"],
  "confirmed": true,
  "img": "string"
}

Use the returned id in the following request to create the token.

Create persistent Service Token

Path:

/api/v1/tokens

Request Body:

{
  "accountId": "PASTE SERVICE ACCOUNT ID HERE",
  "expiresIn": -1,
  "initiator": "PASTE SERVICE ACCOUNT ID HERE",
  "inquirer": "PASTE SERVICE ACCOUNT ID HERE"
}

The returned token is the service token that will be used by the other services to authenticate themselves to the IAM. Copy the value, encode it in base64 (for encoding you can use online tools such as: https://www.base64encode.org/), and then past it into the file found at ./3-Secret/SharedSecret.yaml at the indicated position (REPLACE ME).

Shared Secret Application

Apply the shared secret via

kubectl apply -f ./3-Secret.

Ordinarily, each service would have its own secret for security reasons, but this is simplified for ease of use in a local context

Service Deployment

For each service, you must decide whether to deploy it from the public volume or from source. Each service folder contains a YAML file for both options. If you are deploying manually, you must deactivate the options which you do not want to use. This can be accomplished by changing the filename to remove the .yaml extension, or by deleting the file. Using the setup.sh script automates this process using the -d option flag. Then deploy the services via the following command. This may take a while.

kubectl apply -Rf ./4-Services

Service Availability

The Open Integration Hub is now running and ought to function just as it would in an online context. You can reach the various services via the following URLS:

  • Identity and Access Management. Create and modify users, tenants, roles, and permissions.
    • iam.example.com
  • Secret Service. Securely store authentication data for other applications.
    • skm.example.com
  • Flow Repository. Create, modify, and start/stop integration flows.
    • flow-repository.example.com
  • Audit Log. View event logs spawned by the other services.
    • auditlog.example.com
  • Metadata Repository. Create and modify master data models used by your connectors.
    • metadata.example.com
  • Component Repository. Store and modify connector components.
    • component-repository.example.com
  • Attachment Storage Service. Temporarily store larger files for easier handling in flows.
    • attachment-storage-service.example.com
  • Data Hub. Long-term storage for flow content.
    • data-hub.example.com
  • Integration Layer Service. Perform data operations such as merging or splitting objects.
    • ils.example.com
  • Web UI. A basic browser-based UI to control certain other services.
    • web-ui.example.com

Most of these services have an OpenAPI documentation of their API available through the path /api-docs. You can also check the API Reference Documentation. If you want to learn more about the services, check the Service Documentation or their readmes in the services folder of the GitHub Repository: Open Integration Hub Services

User Guide

After you deployed your own Open Integration Hub instance, check out the User Guide. You will learn how to setup your frist example flow using generic integration components.

User Guide