API Builder

How to Run your API Builder Docker Image on AWS EC2

This guide describes how to run your API Builder Standalone Docker image on an AWS EC2 instance. This is suitable for test and development but for production you will want to stand up a scalable, high availability AWS environment. We’ll discuss these options in future blog posts.

The steps we will follow are:

  • Create and Test Your API Builder 4.0 Docker Image
  • Publish Your Docker Image to Docker Hub (or your Docker Repository)
  • Create an AWS EC2 Linux Instance and SSH into it
  • Install Docker
  • Run The API Builder Docker Image
  • Test your APIs

Note that everything we are covering in this blog post can be accomplished with the AWS Free Tier.

Let’s get started.

Create and Test Your API Builder 4.0 Docker Image

Start from API Builder 4.0 Standalone – From Zero to Dockerized Microservice and create and test your Docker image.

In the prior blog post, we ran our Docker image locally using the following command:

docker run --name lbdemoapi -p 80:8080 -e MONGO_PWD= lbdemoapiimage

Note: AWS can expose port 80 for http traffic so I changed command above to map host port 80 to API Builder port 8080. You can test your API using curl ‘https://localhost:80/api/mongo/dog’

Publish Your Docker Image to Docker Hub (or your Docker Repository)

Now that we have a working Docker Image, we can publish it to a repository so it is available to be installed on other machines. The steps are as follows:

  • Tag your image

    docker tag lbdemoapiimage lbrenman/lbdemoapiimage
  • Publish Your Image
    ddocker image push lbrenman/lbdemoapiimage
  • Make sure your image appears in the repository and add the short and full description by clicking on the Details button

Create an AWS EC2 Linux Instance and SSH into it

Now that we have our Docker image published, let’s go create an AWS EC2 Linux instance to run our Docker image on. The steps are as follows:

  • Create an EC2 instance as follows:

    • Log into the AWS Console and select EC2 from Services. Select the region you’d like the instance to run in. From the screen shot below, I am in Ohio (US East (Ohio))

    • Click on the Launch Instances button

    • Press the Select button on the Amazon Linux AMI 2018.03.0 (HVM), SSD Volume Type – ami-0ff8a91507f77f867 AMI

    • Select the t2.micro (available in the free tier) or whichever type meets your needs

    • Press the Next: Configure Instance Details button

    • We can leave all of the defaults and press the Next: Add Storage button

    • We can leave all of the defaults and press the Next: Add Tags button

    • We can leave all of the defaults and press the Next: Configure Security Group button

    • We can see that only rule in this security group is for SSH so we can SSH into the instance (once launched). We need to add a rule to accept incoming API requests. Click the Add Rule button and select http (port 80).

    • Click the Review and Launch button

    • Press the Launch button and you will presented with the key pair dialog

    • Unless you already have a key pair, select Create a new keypair from the pull down and give your key pair a name (e.g. lbdev-aws-ohio-nov2018) and press the Download Key Pair button

    • Press the Launch Instance button

    • Press the View Instance button and see your instance starting up

    • Click on the (empty) name and name your instance (I called mine ‘Dog API’)

  • SSH into the server using instructions provided in AWS console (with the instance selected, press the Connect button)

    On a mac, in terminal your ssh session should look similar to the following:

Install Docker

Now we need to install Docker on this Linux instance using the instructions here

sudo yum update -y

sudo yum install -y docker

sudo service docker start

sudo usermod -a -G docker ec2-user


SSH back in to the instance and make sure the ec2-user can run Docker by executing the following command:

docker info

If you get a valid response (as follows) then Docker was installed properly

Run The API Builder Docker Image

  • Login to your Docker repository (e.g. Docker Hub)

    docker login

  • Pull the image from the repo (e.g. Docker Hub)

    docker pull lbrenman/lbdemoapiimage

  • Run the image

    docker run --name lbdemoapi --restart always -p 80:8080 -e MONGO_PWD=<MongoDB password> lbrenman/lbdemoapiimage

    Note that the –restart option will ensure that the API Builder Docker image will run if the instance is restarted for any reason

    You should see the API Builder project console indicating the app is running and ready to receive API requests

Test your APIs

Get your instance Public IP address or public DNS entry form the AWS Portal and test your API from your host computer in terminal (or from Postman or the Browser, …).

Note that your IP Address/DNS entry will change if you stop and restart your instance. Use Elastic IP to insure that the IP address/DNS entry doesn’t change.

curl 'https://<instance IP or public DNS address>/api/mongo/dog'

You can get your instance Public IP Address or Public DNS entry from the AWS Console EC2 Instance page on the bottom of the page when you select your instance as shown below:

Test your API from your host computer in a terminal

Note that if your instance does not show a public DNS, you can enable this as follows:

  • Go to console.aws.amazon.com
  • Go To Services -> VPC
  • Open Your VPCs
  • select your VPC connected to your EC2 and
  • select Actions => Edit DNS Hostnames —> Change DNS hostnames: to YES


In this blog post, we saw how easy it is to deploy our API Builder Docker image on AWS EC2. In future blog posts, we’ll look at leveraging AWS for auto-scaling and high availability.

It is worth noting that our API should be secured using the Axway API Gateway. You can read more about Axway API Gateway here.