Home
/
/
/
Install IBM API Connect on personal (Windows or Linux) system
api-connect-datapower-process-running
July 23, 2018

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.

Please take a look at my latest blog on how to install APIC v22018 local test environment in your personal system: https://iteritory.com/install-ibm-api-connect-lte-in-local-windows-system/

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 –

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

    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

    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 –

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.
  •  It will clone the git project in the local folder (F:\api folder in my case).

    apiconnect-docker-git-clone-command

    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

    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.
  • 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 🙂

  • 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 –

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 –
    • Now issue the following command –
    • 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 –

      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 –

  • 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
  • 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.
  • 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

    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 –
  • 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

87
Sadruddin Md

Mohammed is a technology enthusiast with keen interest in system designing, solution architecture, integration/middleware, andriod etc.

You might also like

8 Responses

  1. 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

    49Reply
  2. 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 🙂

    48Reply
  3. 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.

    49Reply
  4. 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

    50Reply
  5. 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

    53Reply
    • 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?

      41Reply
  6. Sanchit Gupta
     October 13, 2021

    Thanks 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:

    10Reply

Write a response

This site uses Akismet to reduce spam. Learn how your comment data is processed.