When I recently installed the IBM API Connect Developer Toolkit, I ran into some problems that I want to share in this blog to help prevent you from running into the same problems. Despite some of the great resources you can find on API Connect I did not find a complete set of instructions and tips that help avoid some of the pitfalls.
Especially if you want to use the DataPower Gateway to test your API Connect projects locally, I think reading this blog might help to make the installation a smooth experience.
Installing API Connect Developer Toolkit
For working with the tookit the IBM Knowledge Center provides a good tutorial that also describes the steps involved in installing the toolkit: https://www.ibm.com/support/knowledgecenter/en/SSFS6T/com.ibm.apic.toolkit.doc/tapim_cli_install.html
However in addition to these instructions I can share two tips that would have helped me earlier on:
- Do not ignore the instruction to install a supported version of Node.js: 4.x or 6.x (recommended). Unfortunately I needed to downgrade my newer version of Node.js to version 6.x before I managed to run the toolkit without problems.
For those of you running Ubuntu or similar distributions you can use the package manager to install version 6.x with these commands:
sudo curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs
This gave me Node version v6.12.0 and npm version 3.10.10 (for npm version 3.x is supported).
You can check your version of Node.js and npm with the ‘node -v’ and ‘npm -v’ commands.
- When you need to use ‘sudo’ to install node.js you will probably need to use the --unsafe-perm option when installing the toolkit:
sudo npm install --unsafe-perm -g apiconnect (instead of: npm install -g apiconnect)
Check you’re version of API Connect (and accept the license) with this command:
Installing the DataPower Gateway
If you want to test your API Connect projects locally with the toolkit you can choose between the Micro Gateway (default) and the DataPower Gateway. The DataPower Gateway gives you more options when assembling your project and is equivalent to the gateway used when you publish your project to the IBM Cloud.
In order to run the DataPower Gateway you need to run the DataPower Docker image.
Next to Docker itself (v1.13 or higher) you also need to have Docker Compose installed (v1.11 or higher). When I tried installing Docker Compose on Ubuntu using the package manager with command ‘apt-get install docker-compose’ I got version 1.18 with unkown build that gave me an error when creating the gateway. I needed to install the latest stabile version 1.17.x :
sudo curl -L https://github.com/docker/compose/releases/download/1.17.1/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
See GitHub for the latest release: https://github.com/docker/compose/releases
You also need to make sure you can run Docker commands without using ‘sudo’, try for instance the ‘docker images’ command. If you get a ‘permission denied’ error then add the current user to the docker group:
sudo groupadd docker
sudo usermod -aG docker $USER
Then you need to reboot for the changes to take effect.
Also if you work inside a Virtual Machine make sure you meet at least the following hardware requirements:
Now it is time to install and run the DataPower Docker image. With the instructions on the IBM Knowledge Center (https://www.ibm.com/support/knowledgecenter/SSFS6T/com.ibm.apic.toolkit.doc/tapim_apic_test_with_dpdockergateway.html) the DataPower Docker image is installed and started through the API Designer (the webinterface of the toolkit) when you click on the ‘Start the servers’ icon. Unfortunately when there are errors during this process this is not apparent for the user and it just looks like nothing happens. A better option is to use the package manager following these instructions: https://www.npmjs.com/package/apiconnect-init-datapower-gateway
First install the package that automates the building of the Docker image with this command:
sudo npm install -g apiconnect-init-datapower-gateway
Then I used the default build option:
apic-init-dp v5 (do not use ‘sudo’ with this command!)
If your system does not meet all requirements the build will fail and an explanation is printed on the screen. Of course since you followed all instructions in this blog this will not happen to you…
Testing the DataPower Gateway
Now you should have a working installation of the DataPower Gateway. In order to check if this is indeed the case you first need to create an API Connect project to test it with.
An easy way to create an API Connect (or Loopback) project is to follow this tutorial on the IBM Knowledge Center:
This will create a basic API Connect project, but to test it you will need to be able to also store and retrieve some data. You can do that by following the follow up article on the IBM Knowledge Center:
Once you completed these steps you are able to test the gateway. If you keep following the tutorial on the IBM Knowledge Center you will test the project with the Micro Gateway. However we want to use the DataPower Gateway. To do this you must first tell your project to use the DataPower Gateway by adding it to the Swagger file. You can manually edit this file (the acme-bank.yaml file in the definitions folder of your project when you followed the above mentioned tutorial) or you can use the API Designer for this.
First open the project folder (acme-bank) in your terminal and then start the API Designer with this command:
This will open up a browser with the API Designer. You can then open the acme-bank API and switch to the Assemble view where you can select the DataPower Gateway:
Don’t forget to save your project. You can check the acme-bank.yaml file to see the gateway property was added to the end of the file (to the x-ibm-configuration block):
You can now start the gateway with the ‘Start the servers’ icon in lower left corner of the API Designer. This will open up a pop-up window indicating the steps that must be passed to start the gateway. This may take a few minutes but eventually the pop-op window should close and you will see the gateway has started.
If things take too long you might want to check if everything is still OK. You can do that by opening up a new terminal window and change to the acme-bank folder, then issue this command:
You should see:
Service acme-bank running on port 4001. Access the application dashboard at http://127.0.0.1:4001/appmetrics-dash
Service acme-bank-gw is still starting.
If you see ‘Service acme-bank-gw failed to start’ you know it went wrong. Try adding more memory to your VM if this happens.
You can also start the gateway (from within the acme-bank folder) with this command:
apic start (this may take a minute or two)
Once the gateway is running you can test your API Connect acme-bank project by continuing the tutorial: https://www.ibm.com/support/knowledgecenter/en/SSFS6T/com.ibm.apic.toolkit.doc/tutorial_cli_project_test.html
When you start the gateway it will now start the DataPower Gateway instead of the Micro Gateway.