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.
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 –
1 2 3 4 |
System with 8 GB RAM Windows 10 Professional || Ubuntu 18.04 LTS (This tutorial covers both) Little knowledge of git Little knowledge of docker |
Install Docker
- 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.
- 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 –
- You can close this window after checking the versions are appropriate.
- 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 –
12345$ docker -vDocker version 18.06.0-ce, build 0ffa825$ docker-compose -vdocker-compose version 1.22.0, build f46880fe
Clone GIT project
- 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.
1git clone https://github.com/strongloop/apiconnect-docker - It will clone the git project in the local folder (F:\api folder in my case).
- 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.
- 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.
1git 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 🙂
1docker 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 –
12345ACCEPT_LICENSE=trueAPIC_VERSION=v5.0.6.0SMTP_HOST=emailSMTP_PORT=5025SMTP_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 –
12FROM ibmcom/apiconnect:manager-v5.0.6.0ADD --chown=root:root get-os-info.sh /opt/ibm/informix/apim/get-os-info.sh - Now issue the following command –
1sudo 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.
-
Update the docker-compose file
-
- 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 –
1234567email:image: gessnerfl/fake-smtp-servercontainer_name: emailports:- "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. - 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 –
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130version: '2'services:make-ssh-keys:build: config-ssh-keyscontainer_name: make-ssh-keysvolumes:- config_ssh_keys:/keys:rwemail:image: gessnerfl/fake-smtp-servercontainer_name: emailports:- "5080:5080"networks:- ibmnetesmaster:build: elasticsearch-mastercontainer_name: esmasternetworks:- ibmnetvolumes:- es_data:/usr/share/elasticsearch/datadatapower:build: datapowercontainer_name: datapowernetworks:- ibmnetenvironment:- DATAPOWER_ACCEPT_LICENSE=$ACCEPT_LICENSEapim:image: manager-v5.0.6.0-ifix:latestmem_limit: 2048mvolumes:- apim_ihvar:/ihvar- apim_wip:/wip- config_ssh_keys:/keys:roenvironment:- 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_LICENSEcontainer_name: apimnetworks:- ibmnetdepends_on:- make-ssh-keys- esmasteribmportal: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_LICENSEvolumes:- ibmportal_var:/var- ibmportal_etc:/etc- config_ssh_keys:/keys:rocontainer_name: ibmportaldepends_on:- make-ssh-keys- apimnetworks:- ibmnetmicroservice:build: microservicecontainer_name: microservicenetworks:- ibmnetlogstash:image: ibmcom/apiconnect:logstash-${APIC_VERSION}environment:- ES_HOST=esmaster- MGMT_HOST=apim- DB_HOST=apim- ACCEPT_LICENSEnetworks:- ibmnetcontainer_name: ibmlogstashdepends_on:- apim- esmasternginx:build: sni-proxyenvironment:- PORTAL_DNS=ibmportal- APIM_DNS=apim- GATEWAY_DNS=datapowerports:- "443:443"container_name: nginxdepends_on:- ibmportal- datapower- apimnetworks:- ibmnetvolumes: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
1sudo 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.
1docker-compose ps - For Ubuntu/Linux, add a sudo before the command if required.
- The result of the above command will be something like below –
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 –
1234560.0.0.0 ibmportal0.0.0.0 datapower0.0.0.0 microservice0.0.0.0 gwadmin0.0.0.0 apim0.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.
Daniel Coman
August 31, 2018Hi! 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
Sadruddin Md
September 4, 2018HI 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 🙂
Abdelhamid Fouad Ghareeb
January 11, 2019Hi ,
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.
Sadruddin Md
January 11, 2019Hi @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
Maneesh M
March 1, 2019I 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
Sadruddin Md
March 2, 2019Yes.. 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?
Sanchit Gupta
October 13, 2021Thanks for such a nice descriptive steps for API Connect installation.
I was trying the above steps with the latest ifix image..but seems like IBM has removed all the images.
Could you help me with any unofficial images for api connect ?
Below is the compose file.
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:
Sadruddin Md
October 13, 2021Thanks for your comment. Please note that this method of setting up APIC is no more available. Please check the blog on the latest approach here: https://iteritory.com/install-ibm-api-connect-lte-in-local-windows-system/