Install IBM API Connect on personal (Windows or Linux) system

Introduction

When I started exploring IBM API Connect, the first thing that hit me was can we set it up in my local system to run and test APIs? Or do we have to always go to bluemix portal and create a trial account for exploring API connect. I started searching through internet. Guess what!! I got some resources from github and IBM knowledge centre on how easily you can install API connect in your local system without much hassle. In this tutorial, I will document my learning on how to install IBM API Connect on personal windows or linux system. Curious to know how easy it’s to install a complex product like API connect (with various components) in your local system with complete control? Well, so read on.

This tutorial has been significantly updated since it was published first. We have covered all possible issues and made it easier as well

Tech Stack

I started writing the tutorial with Windows 10 professional as my base OS. However, my system started reaching 100% disk usage issue and was a bit unstable while it was running. Mostly that was because of the issue of my OS itself. I spent couple of days doing everything that is there on internet to solve this disk usage issue. But, nothing worked. I didn’t have patience to spend more time on it. Hence, installed Ubuntu as a dual boot. However, you can use Windows operating system given your system also does not reach that annoying 100% disk usage issue.

To install IBM API Connect in your local, you need to have little knowledge of docker. As this is not docker tutorial, hence I will suggest you to go through some materials in internet to make yourself familiar with docker.

A little knowledge of git will also be useful. However, if you don’t know, don’t panic. I will try and cover alternate as well. So, I have you covered either way.

All in all, below is the list of all the technologies used here in this tutorial –

System with 8 GB RAM
Windows 10 Professional || Ubuntu 18.04 LTS (This tutorial covers both)
Little knowledge of git
Little knowledge of docker

System with 8 GB RAM

Windows 10 Professional || Ubuntu 18.04 LTS (This tutorial covers both)

Little knowledge of git

Little knowledge of docker

This tutorial covers both Windows and Linux installation process. When using linux,I have used sudo before the commands. You may or may not need to use sudo before the commands depending on your system setup.

Install Docker

Windows

If you have not already installed Docker in your system, this is the time. Head to this docker page, install docker for windows as applicable for your version of Windows Operating System. In my case, I am using Windows 10 professional (Yes, I spent money to upgrade my OS from HOME to Professional!!). I downloaded the docker community edition from the docker store. Once downloaded, install it by double clicking on the .exe file. Installation steps are very intuitive and easy. Just go with the flow and finish off the installation.
Double click on the Docker for Windows shortcut to start docker.
In this process, you may see a popup asking you to enable Hyper-V for windows. Docker for Windows requires Microsoft Hyper-V to run. Click on “Ok” button in the popup (check the screen grab below) to enable it. Your system will need to be restarted, so let it happen.
docker-enable-hyperv-windows10
As per the official documentation, we must have the following versions or above to run API Connect.
- docker 1.12.0 or later.
- docker-compose 1.8.1 or later.
By the time, you are reading this blog, we are much beyond the above versions. Hence, we are covered.
Nevertheless, once docker is installed, we must check the versions installed. Open the command prompt, run following two commands
- docker -v
- docker-compose -v
While writing the blog, following are the versions in my system –
ibm-api-connect-docker-version
You can close this window after checking the versions are appropriate.

Linux (Ubuntu)

If you don’t have docker in your Ubuntu (or any other Linux) machine yet, head to this “install docker on linux” page of official docker documentation and for installing docker-compose, hit this docker documentation or this digital ocean blog.. It’s very well-explained and I won’t cover that as part of this tutorial.
As per the official documentation, we must have the following versions or above to run API Connect.
- docker 1.12.0 or later.
- docker-compose 1.8.1 or later.
By the time, you are reading this blog, we are much beyond the above versions. Hence, we are covered.
Nevertheless, once docker is installed, we must check the versions installed. Open the command prompt, run following two commands
- docker -v
- docker-compose -v
While writing the blog, following are the versions in my system –

$ docker -v Docker version 18.06.0-ce, build 0ffa825 $ docker-compose -v docker-compose version 1.22.0, build f46880fe

1
2
3
4
5

$ docker -v
Docker version 18.06.0-ce, build 0ffa825

$ docker-compose -v
docker-compose version 1.22.0, build f46880fe

Clone GIT project

Windows

Now, choose any folder location in your system where we will clone the apiconnect docker project from github. In my Windows system, I have chosen “F:\api”. Let’s go to this folder, right click and launch git bash terminal.
Write the following command and hit enter.

git clone

git clone https://github.com/strongloop/apiconnect-docker

1

git clone https://github.com/strongloop/apiconnect-docker
It will clone the git project in the local folder (F:\api folder in my case).
apiconnect-docker-git-clone-command
Don’t worry if you are not aware a bit of GIT. You can just open this page from browser and click on the “clone or download” button and then click on the Download ZIP. This will download a zipped project in your local; extract it appropriate location in your system.
apiconnect-docker-git-download

Linux (Ubuntu)

Choose any folder location in your system where we will clone the apiconnect docker project from github. In my system, I have chosen “/home/mohammed/api”. Let’s go to this folder, hit the git command.
Write the following command and hit enter.

git clone

git clone https://github.com/strongloop/apiconnect-docker

1

git clone https://github.com/strongloop/apiconnect-docker
My assumption is you have already installed git in Ubuntu. If not, you may do a little research in google on how to install git. There are plenty of blogs on the same. You may also instead download the zip and extract it.

License Acceptance

Open a command prompt and change your directory to the location you have downloaded/cloned the project. As mentioned earlier, for me it’ll be F:\api\apiconnect-docker in Windows and /home/mohammed/api/apiconnect-docker in Ubuntu.
Run the following command from command prompt to view the license. It will take a while to download and show the license; have patience! That’s the key 🙂

View API Connect License

docker run -it --rm --env SHOW_LICENSE=1 ibmcom/apiconnect:manager-v5.0.6.0

1

docker run -it --rm --env SHOW_LICENSE=1 ibmcom/apiconnect:manager-v5.0.6.0
In order to assert license acceptance, we need to make some changes in the .env file located in project root directory. In my case the .env file location is F:\api\apiconnect-docker for Windows and /home/mohammed/api/apiconnect-docker in Ubuntu.
We will have to specify environment variable ACCEPT_LICENSE=true as an acceptance to the license. (Check the modified file in below section)

SMTP Server Configuration (.env file)

We need a SMTP server for setting up API connect.This configuration will also be done in .env file.
You may use any SMTP server like GMAIL etc or your company’s should that be possible. However, in this example, we will a fake SMTP server available locally. This will help us to be flexible. Mention the smtp host as email and smtp port as 5025.
After the necessary modifications in the license agreement and the SMTP configuration, the .env file looks like –

ACCEPT_LICENSE=true APIC_VERSION=v5.0.6.0 SMTP_HOST=email SMTP_PORT=5025 SMTP_SENDER=donotreply@iteritory.com

1
2
3
4
5

ACCEPT_LICENSE=true
APIC_VERSION=v5.0.6.0
SMTP_HOST=email
SMTP_PORT=5025
SMTP_SENDER=donotreply@iteritory.com

Choose appropriate Gateway

Now, we need to make a decision as to which gateway service shall we choose. We have two options – Datapower gateway or Micro gateway. While Datapower gives us more flexibility and options, micro gateway is very lightweight. In our case, we will opt for Datapower Gateway Service.

Setup the docker environment

Update API manager image (to address issue#39)
- Create a directory as a sibling to apiconnect-docker with the name apim. Change your directory to newly created apim folder. So, in my scenario the absolute path to the directory is /home/mohammed/api/apim. Following steps will take place inside this directory.
- Click in this github link to download the zipped shell script.Unzip and extract the shell script inside apim directory. Delete the .gz file.
- Give appropriate permission to the .shell file by running chmod a+x get-os-info.sh
- Create a file with the name Dockerfile
- Populate this file with below content –
  
  Dockerfile content
  
  FROM ibmcom/apiconnect:manager-v5.0.6.0 ADD --chown=root:root get-os-info.sh /opt/ibm/informix/apim/get-os-info.sh
  
  1
  2
  
  FROM ibmcom/apiconnect:manager-v5.0.6.0
  ADD --chown=root:root get-os-info.sh /opt/ibm/informix/apim/get-os-info.sh
- Now issue the following command –
  
  sudo docker build -t manager-v5.0.6.0-ifix .
  
  1
  
  sudo docker build -t manager-v5.0.6.0-ifix .
- Once complete, we will update docker-compose.yaml file to change the apim image to manager-v5.0.6.0-ifix:latest that we created above.
- Stay tuned, I will guide you through the steps. Just don’t make the changes to the .yaml file yet.

Above steps are taken from the resolution of github issue#39. I have put together the same steps mentioned there just for the convenience of readers.

Update the docker-compose file

In one of the previous section, we spoke about using a fake smtp server to trap the emails sent by API connect. We can very well download any fake freely available smtp server from internet and use it. However, connecting to that smtp server from inside the docker containers may turn out to be challenging. At least, I spent a lot of time to figure out how to establish connection to the smtp server from within the doc. Just to ensure, you don’t face the same issue, execute the following steps. This will make your life really smooth. You can thank me later!! 🙂

Traverse back to apiconnect-docker folder. You will notice a file called docker-compose.yaml. This file has all the magic setup. Take a backup of this file with some other name.

Now open this docker-compose.yaml file in any editor (I have used vi in Ubuntu) of your choice and add following segment to file –

  email:
    image: gessnerfl/fake-smtp-server
    container_name: email
    ports:
      - "5080:5080"
    networks:
      - ibmnet

email:

image: gessnerfl/fake-smtp-server

container_name: email

ports:

- "5080:5080"

networks:

- ibmnet

We are going to use a smtp server in a container named email. We will use the GUI of this smtp server thorugh port 5080. We also want the container to run in the same ibmnet network where other containers will also run.

For more detail of this smtp server, you can take a look here and here.

Now it’s time to update the apim image as well with the latest image manager-v5.0.6.0-ifix that we created above. Please note the highlighted line#35 in below content

After all the changes the docker-compose.yaml file looks like below. Highlighted segments are the modifications that we made as part of this tutorial –

version: '2'

services:
  make-ssh-keys:
    build: config-ssh-keys
    container_name: make-ssh-keys
    volumes:
      - config_ssh_keys:/keys:rw

  email:
    image: gessnerfl/fake-smtp-server
    container_name: email
    ports:
      - "5080:5080"
    networks:
      - ibmnet

  esmaster:
    build: elasticsearch-master
    container_name: esmaster
    networks:
      - ibmnet
    volumes:
      - es_data:/usr/share/elasticsearch/data

  datapower:
    build: datapower
    container_name: datapower
    networks:
      - ibmnet
    environment:
      - DATAPOWER_ACCEPT_LICENSE=$ACCEPT_LICENSE

  apim:
    image: manager-v5.0.6.0-ifix:latest
    mem_limit: 2048m
    volumes:
      - apim_ihvar:/ihvar
      - apim_wip:/wip
      - config_ssh_keys:/keys:ro
    environment:
      - MANAGEMENT_CLUSTER_HOST=apim
      - PORTAL_PRIVATE_KEY=/keys/portal
      - PORTAL_PUBLIC_KEY=/keys/portal.pub
      - PORTAL_LB=ibmportal
      - ES_HOST=esmaster
      - ES_PORT=9500
      - SMTP_HOST
      - SMTP_PORT
      - SMTP_USERNAME
      - SMTP_PASSWORD
      - SMTP_SENDER
      - LOGSTASH_HOST=ibmlogstash
      - ACCEPT_LICENSE
    container_name: apim
    networks:
      - ibmnet
    depends_on:
      - make-ssh-keys
      - esmaster

  ibmportal:
    image: ibmcom/apiconnect:portal-${APIC_VERSION}
    environment:
      - PORTAL_LB=ibmportal
      - PORTAL_PUBLIC_KEY=/keys/portal.pub
      - APIC_HOST=apim
      - SMTP_HOST
      - SMTP_PORT
      - SMTP_USERNAME
      - SMTP_PASSWORD
      - SMTP_SENDER
      - ACCEPT_LICENSE
    volumes:
      - ibmportal_var:/var
      - ibmportal_etc:/etc
      - config_ssh_keys:/keys:ro
    container_name: ibmportal
    depends_on:
      - make-ssh-keys
      - apim
    networks:
      - ibmnet

  microservice:
    build: microservice
    container_name: microservice
    networks:
      - ibmnet

  logstash:
    image: ibmcom/apiconnect:logstash-${APIC_VERSION}
    environment:
      - ES_HOST=esmaster
      - MGMT_HOST=apim
      - DB_HOST=apim
      - ACCEPT_LICENSE
    networks:
      - ibmnet
    container_name: ibmlogstash
    depends_on:
      - apim
      - esmaster

  nginx:
    build: sni-proxy
    environment:
      - PORTAL_DNS=ibmportal
      - APIM_DNS=apim
      - GATEWAY_DNS=datapower
    ports:
      - "443:443"
    container_name: nginx
    depends_on:
      - ibmportal
      - datapower
      - apim
    networks:
      - ibmnet

volumes:
  config_ssh_keys:
  apim_ihvar:
  apim_wip:
  ibmportal_var:
  ibmportal_etc:
  es_data:

networks:
  ibmnet:

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

version: '2'

services:

make-ssh-keys:

build: config-ssh-keys

container_name: make-ssh-keys

volumes:

- config_ssh_keys:/keys:rw

email:

image: gessnerfl/fake-smtp-server

container_name: email

ports:

- "5080:5080"

networks:

- ibmnet

esmaster:

build: elasticsearch-master

container_name: esmaster

networks:

- ibmnet

volumes:

- es_data:/usr/share/elasticsearch/data

datapower:

build: datapower

container_name: datapower

networks:

- ibmnet

environment:

- DATAPOWER_ACCEPT_LICENSE=$ACCEPT_LICENSE

apim:

image: manager-v5.0.6.0-ifix:latest

mem_limit: 2048m

volumes:

- apim_ihvar:/ihvar

- apim_wip:/wip

- config_ssh_keys:/keys:ro

environment:

- MANAGEMENT_CLUSTER_HOST=apim

- PORTAL_PRIVATE_KEY=/keys/portal

- PORTAL_PUBLIC_KEY=/keys/portal.pub

- PORTAL_LB=ibmportal

- ES_HOST=esmaster

- ES_PORT=9500

- SMTP_HOST

- SMTP_PORT

- SMTP_USERNAME

- SMTP_PASSWORD

- SMTP_SENDER

- LOGSTASH_HOST=ibmlogstash

- ACCEPT_LICENSE

container_name: apim

networks:

- ibmnet

depends_on:

- make-ssh-keys

- esmaster

ibmportal:

image: ibmcom/apiconnect:portal-${APIC_VERSION}

environment:

- PORTAL_LB=ibmportal

- PORTAL_PUBLIC_KEY=/keys/portal.pub

- APIC_HOST=apim

- SMTP_HOST

- SMTP_PORT

- SMTP_USERNAME

- SMTP_PASSWORD

- SMTP_SENDER

- ACCEPT_LICENSE

volumes:

- ibmportal_var:/var

- ibmportal_etc:/etc

- config_ssh_keys:/keys:ro

container_name: ibmportal

depends_on:

- make-ssh-keys

- apim

networks:

- ibmnet

microservice:

build: microservice

container_name: microservice

networks:

- ibmnet

logstash:

image: ibmcom/apiconnect:logstash-${APIC_VERSION}

environment:

- ES_HOST=esmaster

- MGMT_HOST=apim

- DB_HOST=apim

- ACCEPT_LICENSE

networks:

- ibmnet

container_name: ibmlogstash

depends_on:

- apim

- esmaster

nginx:

build: sni-proxy

environment:

- PORTAL_DNS=ibmportal

- APIM_DNS=apim

- GATEWAY_DNS=datapower

ports:

- "443:443"

container_name: nginx

depends_on:

- ibmportal

- datapower

- apim

networks:

- ibmnet

volumes:

config_ssh_keys:

apim_ihvar:

apim_wip:

ibmportal_var:

ibmportal_etc:

es_data:

networks:

ibmnet:

Update the Dockerfiles for microservice and microwgateway [issue#43]-
- Change directory to apiconnect-docker\microservice folder.
- Locate the file with the name Dockerfile
- Open it with any text editor, change the first line in the file. Change FROM node:4-slim to FROM node:8-slim
- Save the file.
- We will do similar change in the Dockerfile present in apiconnect-docker\microgateway folder as well in case we want to install microgateway. Open it with any text editor, change the first line in the file. Change FROM node:4-slim to FROM node:8-slim
- Save the file.

Start API Connect containers

Open command prompt and ensure that you are in project root directory (which in my case is F:\api\apiconnect-docker in Windows and /home/mohammed/api/apiconnect-docker in Ubuntu)
Fire the following command

sudo docker-compose up -d

1

sudo docker-compose up -d
Wait for all processing and downloads to happen. This may take quite sometime to start all the service. Have patience
At the end of it, you will see a screen something like below –
Now let’s run the following command in Windows command prompt while we are in F:\api\apiconnect-docker folder in Windows or /home/mohammed/api/apiconnect-docker folder in Ubuntu.

docker-compose ps

1

docker-compose ps
For Ubuntu/Linux, add a sudo before the command if required.
The result of the above command will be something like below –
api-connect-datapower-process-running

Configure /etc/hosts

Now that we have successfully, completed above tasks, we will do some more steps to enable the easy access to these services/components we just installed.
Open the /etc/hosts file and add following entries –

0.0.0.0 ibmportal 0.0.0.0 datapower 0.0.0.0 microservice 0.0.0.0 gwadmin 0.0.0.0 apim 0.0.0.0 email

1
2
3
4
5
6

0.0.0.0 ibmportal
0.0.0.0 datapower
0.0.0.0 microservice
0.0.0.0 gwadmin
0.0.0.0 apim
0.0.0.0 email
For Windows, you can locate the hosts file in this directory –> C:\Windows\System32\Drivers\etc\hosts and make the similar change. However, in case of windows, you can’t put 0.0.0.0. Instead, you should get the actual IPs of the containers and put it over here.
Bingo!!, we are done 🙂

Run and Verify installation

Hit the https://apim/cmc/ (API Cloud Manager URL) or may be hit the https://gwadmin (Datapower URL).
Also hit http://email:5080; this is where will will receive all the emails from API Connect as and when we start using it.
Well, the stage is set for the magic to happen !! 😉

Conclusion

Well folks, we just installed IBM API Connect in our local systems. It’s pretty easy!! Isn’t it? Please let me know should you face any problem in completing this. I’ll try and help as much as I can. See you later, happy installing!!

Also, please go thought the next blog post, where I have covered how to setup and configure the API Connect platform and make it ready for the development.

Reference

Daniel Coman
August 31, 2018

Hi! Thank you very much for this useful post!
One question: is there any possibility to upgrade the Api Management version from 5.0.6 to 5.0.8.1 somehow?

Thanks in advance!
Daniel

5Reply
Sadruddin Md
September 4, 2018

HI Daniel, sorry for the late reply. Unfortunately, not possible at this point with the docker. I know it’s little frustrating, but as I see in their github documentation, they have not published the mentioned version. I too am looking forward to it 🙂

4Reply
Abdelhamid Fouad Ghareeb
January 11, 2019

Hi ,
I am facing the below error in windows while trying to run docker run command as mentioned in article
Unable to find image ‘ibmcom/apiconnect:manager-v5.0.6.0’ locally

Please advice.

1Reply
Sadruddin Md
January 11, 2019

Hi @Abdelhamid, there is some workaround to do for the manager image. Did you follow the steps I mentioned above. If you have done and still getting the above error, please paste your docker-compose file

3Reply
Maneesh M
March 1, 2019

I get the error – docker: Error response from daemon: pull access denied for ibmcom/apiconnect, repository does not exist or may require ‘docker login’.

while running the license

2Reply
- Sadruddin Md
  March 2, 2019
  
  Yes.. I also noticed the same. IBM has removed the repository from docker hub. However, I also noticed that there are few unofficial images for api connect. May be you can take a look and update if it works for you?
  
  LikeReply

iteritory.com

Install IBM API Connect on personal (Windows or Linux) system

Introduction

Tech Stack

Install Docker

Clone GIT project

License Acceptance

SMTP Server Configuration (.env file)

Choose appropriate Gateway

Setup the docker environment

Update API manager image (to address issue#39)

Update the docker-compose file

Update the Dockerfiles for microservice and microwgateway [issue#43]-

Start API Connect containers

Configure /etc/hosts

Run and Verify installation

Conclusion

Reference

Sadruddin Md

6 Responses

Daniel Coman

Sadruddin Md

Abdelhamid Fouad Ghareeb

Sadruddin Md

Maneesh M

Sadruddin Md

Write a response

Introduction

Tech Stack

Install Docker

Clone GIT project

License Acceptance

SMTP Server Configuration (.env file)

Choose appropriate Gateway

Setup the docker environment

Update API manager image (to address issue#39)

Update the docker-compose file

Update the Dockerfiles for microservice and microwgateway [issue#43]-

Start API Connect containers

Configure /etc/hosts

Run and Verify installation

Conclusion

Reference

Sadruddin Md

You might also like

6 Responses

Daniel Coman

Sadruddin Md

Abdelhamid Fouad Ghareeb

Sadruddin Md

Maneesh M

Sadruddin Md

Write a response