Document type Number 1 (19)

Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Blog Post

IBM API Connect on Docker (or Toolbox)

IBM is working hard to make some of its products available to the public as “non-production” releases.
“Non-production” would mean that you can use it for development, test, demo, or whatever as long as
you don’t use it in a “production” environment.

You can freely download and play around with the Docker version of API Connect.

The IBM documentation can be found here: https://developer.ibm.com/apiconnect/getting-started/.

For Docker:
https://www.ibm.com/support/knowledgecenter/SSMNED_5.0.0/com.ibm.apic.install.doc/tapic_docker
_install.html#task_g33_f4b_dy__install_in_docker

To get started you obviously first need to install Docker. If you are on Linux or MAC you can run
Docker “native”, meaning you run the Docker containers directly on your host computer.
This is also true if you are lucky enough to have Windows 10 version 10586 or above (a.k.a. “the
November release or 1511). To find out, hit [Win]+R and give the command “winver” in the Run…
box.

If you sit on an older install and Windows Update don’t give you the option to upgrade (which it
normally doesn’t for corporate Enterprise installs), fear not, you can run Docker Toolbox!

Docker Toolbox is essentially a Docker container that runs in Oracle VM VirtualBox and your
DataPower container in turn runs in that. That maybe sounds very complex and complicated but it all
installs seamlessly and you don’t have to worry!

www.enfogroup.com
 Document type Number 2 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Just install the Docker software first and at the end of the installation of Toolbox you’ll see a
command window (see page 7 for Docker for Windows native else continue here):

This will run some scripts and setup a new local subnet for the Docker network. You’ll be asked
several times for permissions to allow operations, just answer Yes to all…

Once completed you’ll see the Docker Whale and take note of the IP address (in my case
192.168.99.100):

As the DataPower image has some requirements for memory and CPU’s we’ll have to up the defaults
in VirtualBox.

Stop the default image with “docker-machine stop”

Then find and launch Oracle VM Virtual box from your Start menu or Desktop.

www.enfogroup.com
 Document type Number 3 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Make sure the default machine is “Powered off” and the right-click it and chose “Settings” from the
menu and go to System:

Up the memory to at least 8196 MB!

If you have 16 GB on your computer this is not a problem but the container might not start if you only
have 8 GB of physical memory installed (or you Windows computer might crash).

www.enfogroup.com
 Document type Number 4 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Next chose “Processor” and set it to 2:

If you see an “Invalid settings”:

Click the exclamation point and see what it is. Normally it is the display size or memory so adjust that
at the same time, e.g.:

Exit out with OK and go back to the Docker CMD window and start the default machine again:

docker-machine start

www.enfogroup.com
 Document type Number 5 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

If you see a prompt like this:

Just run “docker-machine env”, it will print out the new details for the changed container.

www.enfogroup.com
 Document type Number 6 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Using Docker for Windows native you’ll instead see this at the end of the installation:

Once started you’ll see a small Whale in the taskbar:

Right-click the Whale and select [Settings…]. I prefer not to have Docker start automatically when I
login so I recommend unticking that.

Next go to Shared Drives and select C: or D: depending on which you will use:

www.enfogroup.com
 Document type Number 7 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

You will be prompted for your credentials to access the drive!

If/when you change password you MUST remember to change it here again else your Shares won’t
work!

If you then get a message about Firewall you must open port 445 in your local Firewall!

Docker installer automatically adds an opening in Windows Firewall but if you run any third party
Antivirus/Firewall program on your computer you need to open the port there manually.
If you are on a corporate network (i.e. in a domain) you might have a managed local firewall, e.g.
Symatec SPEM, and then you might need to contact helpdesk/services to get the port opened up for
you.

www.enfogroup.com
 Document type Number 8 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Next we need to up the memory to get DataPower going in the Advanced settings:

If you have 16 GB memory on your laptop and you can spare 8 GB for Docker, great!
Else it will run on 8 GB physical memory but with some lag… You must set it to 8 GB though!

If you get any other error go here for help: https://docs.docker.com/docker-for-windows/troubleshoot/

www.enfogroup.com
 Document type Number 9 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Now everything you need is installed!

Fire up the Docker CMD for Toolbox or Windows CMD or Power Shell (which I recommend) for
Docker native.
Run the command “docker version” to see that all is OK:

If not, then go here: https://docs.docker.com/docker-for-windows/troubleshoot/

www.enfogroup.com
 Document type Number 10 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Ready to go with API Connect install!

DO NOT RUN ANY OTHER DOCKER CONTAINER WHILE INSTALLING API CONNECT IF
YOU “ONLY” HAVE 8 GB MEMORY SET!

For API Connect we need to pull it from GitHub so if you don’t have Git installed go to: https://git-
scm.com/downloads

After Git is installed select a directory on your disk where to pull the container setup to. Mine is on:
D:\VMwares\Hyper-V\Images\api-connect\

Next open a CMD prompt (or terminal) and enter:

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

Now it will start downloading a ton of stuff and images, just sit tight and wait until it is completed.

Once complete enter the sub-directory “apiconnect-docker” and edit the file called “.env”. Make sure
you open it in a “real” editor, e.g. Notepad++, and not Windows Notepad as that will append “.txt” to
the file which we don’t want!

The ACCEPT_LICENSE=true entry is commented out by default, you must remove the preceding #
character!

You should also make sure you have a SMTP server as API Connect is dependent on being able to
send e-mails with passwords and to add accounts.

If you are attending this as an Enfo education/Academy you will be provided with a SMTP server to
use. You MUST have a SMTP server setup as the logins will be e-mailed to you by API Connect!

www.enfogroup.com
 Document type Number 11 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Now open the “DockerFile” in the “.\apiconnect-docker\datapower” directory:

If it says “datapower:latest” you have two options, either you change it to “datapower:7.5.2”
or you add “USER root” according to line 4 above.

To enable access to all the services, edit your local /etc/hosts file in Linux/MAC or lmhosts in
Windows (C:\Windows\System32\drivers\etc) to map the IP address of your Docker host to
the IBM API Connect host names, depending on whether you want to use DataPower Gateway or
Micro Gateway as the gateway service, as follows:

Linux:

DataPower: <docker_host_ip_address> apim ibmportal datapower microservice

Micro Gateway: <docker_host_ip_address> apim ibmportal microgateway microservice

On Windows you have to create it on four lines with the IP first on all of them (that is four lines
starting with the same IP!).

127.0.0.1 apim
127.0.0.1 ibmportal
127.0.0.1 datapower
127.0.0.1 microservice
127.0.0.1 gwadmin

For Docker Toolbox you need your Docker IP which was visible by the Whale initially. If you have
forgotten or didn’t see it, just start another Docker CMD window and hit command “docker-machine
ip”:

If you run on Docker Native you just use “127.0.0.1” (localhost)!

www.enfogroup.com
 Document type Number 12 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

After saving the lmhosts file on Windows open a Power Shell or CMD with Admin and enter:
nbtstat -R

This will refresh the hosts list.

Next you are ready to start API Connect. I strongly recommended to go with the DataPower
implementation as you’ll get more functions and that is what most customers are using.

In a Docker terminal window, change to the root folder of your local repository clone, and run the
following command, depending on whether you want to use DataPower or Micro Gateway as the
gateway service:

docker-compose up -d

Or for MicroGateway:

docker-compose -f docker-compose-microgateway.yaml up -d

Be patient!

Starting all the server can take several minutes even though the Docker containers are
reporting an “up” state!

www.enfogroup.com
 Document type Number 13 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Confirm that the IBM API Connect services are running by entering the following command,
depending on whether you want to use DataPower Gateway or Micro Gateway as the gateway
service:

DataPower: docker-compose ps

Micro Gateway: docker-compose -f docker-compose-microgateway.yaml ps

You should see a response similar to the following (if you are using the Micro Gateway, microgateway
is listed instead of datapower):

Name Command State Ports

------------------------------------------------------------------------------------------------------
apim /tini -- /startup.sh Up
datapower /start.sh Up 443/tcp
dockercompose_make-ssh-keys_1 /bin/sh -c /genkey.sh Exit 0
esmaster /docker-entrypoint.sh /bin ... Up 9200/tcp, 9300/tcp
ibmlogstash /bin/sh -c /startup.sh Up
ibmportal /root/tini -- /root/start_ ... Up
microservice /bin/sh -c /usr/bin/app.sh ... Up 8080/tcp
nginx /bin/sh -c /run.sh Up 0.0.0.0:443->443/tcp, 80/tcp

Now we are going to configure your IBM API Connect cloud. Open the Cloud Manager user interface
in a browser by entering the following URL:

https://apim/cmc

www.enfogroup.com
 Document type Number 14 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

You will have to add a security exception for the certificate as API Connect is using self-signed
certificates.

Log in with the following credentials:

Username: admin
Password: !n0r1t5@C

Accept the license agreement.

On the Create your profile page, enter your email address, and a new password, then click Update
profile. The Cloud Manager user interface opens.

www.enfogroup.com
 Document type Number 15 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

If you selected to run on DataPower then configure the Management service by completing the
following steps:

1. Click Services, then in the DataPower Services pane click the Service Settings icon Service
Settings icon to the far right.

2. Enter datapower in the Address field, then click Save.

3. In the DataPower Services pane, click Add Server, then enter the following details:
• Display Name: idg
• Address: datapower
• Username: admin
• Password: admin
4. Click Create to add the server.

Note! This operation might take a while to complete.

Next we have to add a new provider organization. Do so by completing the following steps:

1. Click the Organizations tab, then click Add.

2. Enter a Display Name and Name of your choice.
• Note! The value of the Name field is included in the organization segment of the URL
for API calls.
3. Click New User and enter your email address in the Email field.
4. Click Add to create the provider organization. An invitation email is sent to the specified email
address.
5. In the invitation email, click the activation link and follow the instructions to sign up.

When you have completed the sign up instructions, the login page for the API Manager user interface
opens; log in with your email address and password. The API Manager user interface opens.

To reopen the API Manager in the future, use the following URL:
https://apim/apim

Remember you use the user “admin” for the Cloud manager (cmc) and your e-mail address for
the API Management console (apim)!

www.enfogroup.com
 Document type Number 16 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Now configure your IBM API Connect Catalog.

1. In the API Manager user interface, click the Navigate to icon , then click Dashboard.

2. Click the Sandbox Catalog to display its details.

MICRO GATEWAY ONLY: Customize the gateway endpoint by completing the following
steps:
a. Click the Settings tab, then click Endpoints.
b. In the Custom Gateway URL field, enter https://microgateway.
c. Click the Save icon to save your gateway customization.

3. Enable the Developer Portal in the Sandbox Catalog by completing the following steps:

a. Click the Settings tab, then click Portal.

b. From the Select Portal drop-down, select IBM Developer Portal. The URL is
set automatically to the following value:
https://ibmportal/organization_name/sb
where organization_name is the Name value that you specified when you
created the provider organization in the previous section.
c. Click the Save icon to save your Developer Portal configuration.

After a few minutes, you will receive an email with a link to the Developer Portal site for the Sandbox
Catalog. The link is single use only link for the administrator account. When the link is active and you
have accessed it, you can change the password of the administrator account.

www.enfogroup.com
 Document type Number 17 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

1. Publish a microservice application to the Sandbox Catalog.

a. Install the IBM API Connect developer toolkit; for details, see Installing the toolkit.
b. Open a command window and navigate to the /apim/docker/docker-
compose/microservice folder in your local repository clone.
c. Enter the command apic login, and supply the following details in response to the prompts:
▪ Server: apim.
▪ Username: your API Manager user interface account email address.
▪ Password: your API Manager user interface account password.
You should receive the response Logged into apim successfully.
d. Enter the following command (all on one line):
e. apic publish definitions/loopback-example-database-product.yaml --catalog sb
--organization organization_name --server apim
where organization_name is the Name value that you specified when you created the provider
organization in the previous section.

2. Configure the Developer Portal.

a. Open the Developer Portal user interface by entering the following URL:
https://ibmportal/organization_name/sb/
where organization_name is the Name value that you specified when you created the provider
organization in the previous section.
You can see the loopback-example-database 1.0.0 microservice in the Featured APIs pane.
b. Click Create an account and follow the instructions to create a Developer Portal account. An
invitation email is send to the specified email address.
Note! You cannot use the same email address as the one you used in the previous section when
creating your provider organization, because this email address is used for the Developer
Portal admin account.
c. Follow the activation link in the invitation email, and log in to the Developer Portal as a developer
by using the account credentials you just specified.
d. Create an App by completing the following steps:
i. Click Apps > Create new App.
ii. Enter microservice for the title, and a description of your choice, then click Submit.

e. Select the Show Client Secret check box and make a note of your client secret because it is
displayed only once. You must supply the client secret when you call an API that requires you to
identify your application by using a client ID and client secret.
Note
The client secret cannot be retrieved. If you forget it, you must reset it.
f. The client ID is hidden; to display the client ID for your application, select the Show check box
for Client ID, and make a note of it. The client ID is displayed and can be hidden again by clearing
the check box.
g. Optional: You can add an additional client ID and client secret to the application. For more details,
see Registering an application.
h. Subscribe to a Plan by completing the following steps:
. Click API Products, then click loopback-example-database (1.0.0) to open the Product details
page.
i. Click Subscribe to subscribe to the default Plan.
ii. Select your microservice App, then click Subscribe.

www.enfogroup.com
 Document type Number 18 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Note! It takes up to 10 minutes for the Micro Gateway to synchronize with

the API Connect Management server. The subscription credentials will be accepted by the Micro
Gateway after the synchronization is complete.

3. Access the microservice APIs through the gateway.

Note! The following commands use sample client ID and client secret values. You must replace these
with your own credentials that you derived in the previous section.
a. Access the POST API through the gateway by running the following command:
b. curl -k --request POST \
c. --url endpoint_url \
d. --header 'accept: application/json' \
e. --header 'content-type: application/json' \
f. --header 'x-ibm-client-id: ad37d0e2-4551-41f7-a011-88f0447f4560' \
g. --header 'x-ibm-client-secret:
yY7xL8hA0iD1tR0qD5hY0kG3rR3nC2eA3mM8iN2yL4hD2bQ2gU' \
--data '{"email":"myemail@myhost.com","createdAt":"2016-11-
26T15:29:45.233Z","lastModifiedAt":"2016-11-25T20:17:02.033Z"}'
h. Access the GET API through the gateway by running the following command:
i. curl -k --request GET \
j. --url endpoint_url \
k. --header 'accept: application/json' \
l. --header 'content-type: application/json' \
m. --header 'x-ibm-client-id: ad37d0e2-4551-41f7-a011-88f0447f4560' \
--header 'x-ibm-client-secret:
yY7xL8hA0iD1tR0qD5hY0kG3rR3nC2eA3mM8iN2yL4hD2bQ2gU'

where endpoint_url has the following value depending on whether you are using the DataPower
Gateway or Micro Gateway as the gateway service:
▪ https://datapower/organization_name/sb/api/Accounts
where organization_name is the Name value that you specified when you created the
provider organization in step 2.f
▪ https://microgateway/api/Accounts

www.enfogroup.com
 Document type Number 19 (19)
Sublemental Attachment

Anders Wasén 8/26/2016 Internal

Some pointers along the way…

Did you run into problems?

If you get any Docker related error go here for help: https://docs.docker.com/docker-for-
windows/troubleshoot/

Start over by removing the container and try again:

Use “docker ps -a” to list all existing containers.

Take note of the identifier, e.g. “6e62e2f3c1be” and the remove the container by “docker rm
6e62e2f3c1be”

Add more ports:

You can’t add more ports on the fly so we have to recreate the container:

1) Stop running container:

docker stop idg

2) Commit the container:

docker commit idg idg02
NOTE: The above, idg02 is a new image that I'm constructing from the idg container.

3) Re-run from the commit’ed image:

docker run -p 9000-9010:9000-9010 -td idg02

Your container will now be named idg02 instead. If you want to go back to the original “idg” again just
remove the original idg (see removing the container above) and the clone once more from idg02 to
idg and finally remove idg02.

Good Luck!

Written by:
Anders Wasén, Enfo Zystems, anders.wasen@enfo.se

www.enfogroup.com