APIcast on Docker

SaaS On-premises 2.0
This is a step-by-step guide to deploy APIcast inside a Docker container ready to be used as a 3scale API gateway.


You will need to configure APIcast in your 3scale Admin Portal as per the APIcast Overview, if you haven't done so already.

Step 1: Install Docker

This guide covers the steps to set up Docker on Red Hat Enterprise Linux (RHEL) 7.

Docker packages provided by Red Hat are released as part of the Extras channel in RHEL. To enable additional repositories, you can use either the Subscription Manager, or Yum config manager, see the RHEL product documentation for details.

For a RHEL 7 deployed on a AWS EC2 instance we'll use the following the instructions:

  • List all repositories:

sudo yum repolist all

Find the *-extras repository.

  • Enable extras repository:

sudo yum-config-manager --enable rhui-REGION-rhel-server-extras

  • Install Docker package:

sudo yum install docker

For other operating systems please refer to the Docker documentation on:

Step 2: Run the Docker Gateway

Start the Docker daemon:

sudo systemctl start docker.service

To check if the Docker daemon is running use the following command:

sudo systemctl status docker.service

You can download a ready to use Docker image from the Red Hat registry:

sudo docker pull registry.access.redhat.com/3scale-amp20/apicast-gateway:1.0

Run APIcast in a Docker container with the command:

sudo docker run --name apicast --rm -p 8080:8080 -e THREESCALE_PORTAL_ENDPOINT=https://<ACCESS_TOKEN>@<DOMAIN>-admin.3scale.net registry.access.redhat.com/3scale-amp20/apicast-gateway:1.0

Here <ACCESS_TOKEN> is an Access Token for the 3scale Account Management API, the Provider Key can also be used instead of the access token, and <DOMAIN>-admin.3scale.net is the URL of your 3scale admin portal.

This command runs a Docker container called "apicast" on port 8080 and grabs the JSON configuration file from your 3scale portal. For other configuration options check out the APIcast Overview guide.

Docker options

Here are some useful options that can be used with docker run command:

  • --rm Automatically remove the container when it exits

  • -d or --detach Run container in background and print container ID. When it is not specified, the container runs in foreground mode, and you can stop it by CTRL + c. When started in detached mode, you can reattach to the container with the docker attach command, for example, docker attach apicast.

  • -p or --publish Publish a container's port to the host. The value should have the format <host port>:<container port>, so -p 80:8080 will bind port 8080 of the container to port 80 of the host machine.

For example, the Management API uses port 8090, so you may want to publish this port by adding -p 8090:8090 to the docker run command.

  • -e or --env Set environment variables

  • -v or --volume Mount a volume. The value is typically represented as <host path>:<container path>[:<options>]. <options> is an optional attribute, it can be set to :ro to specify that the volume will be read only (it is mounted in read-write mode by default). Example: -v /host/path:/container/path:ro.

See the Docker run reference for more information on available options.

Step 3: Testing APIcast

So now your Docker container is running with your own configuration file and the Docker image from the 3scale registry. You will want to test calls through APIcast on port 8080 and provide the correct authentication credentials which you can get from your 3scale account.

Test calls will not only verify that APIcast is running correctly but also that authentication and reporting is being handled successfully.

Note: Make sure that the host you use for the calls is the same that is same as configured in the Public Base URL field on the Integration page.

Step 4: Troubleshooting APIcast on Docker

Cannot connect to the Docker daemon error

If you see the error message:

docker: Cannot connect to the Docker daemon. Is the docker daemon running on this host?.

then it may be that the Docker service hasn't started. You can check the status of the Docker daemon by running sudo systemctl status docker.service.

Make sure you are running as root user, as Docker requires root permissions in RHEL by default (see more information here).

Basic Docker commands

If you started the container in detached mode (-d option) and want to check the logs for the running APIcast instance, you can use the log command:

sudo docker logs <CONTAINER>

where <CONTAINER> is the container name ("apicast" in the example above) or the container ID. You can get the list of the running containers and ther IDs and names with the command sudo docker ps.

To stop the container, run sudo docker stop <CONTAINER>. You can also remove the container by running sudo docker rm <CONTAINER>.

Please refer to Docker commands reference for more information on available commands.

Step 5: Customising the Gateway

There are some customizations that cannot be managed through the admin portal and require writing custom logic to APIcast itself.

Custom Lua logic

The easiest way to customise APIcast logic is to rewrite the existing file with your own and attach it as a volume.

-v $(pwd)/path_to/file.lua:/opt/app-root/src/src/file.lua:ro

The -v flag attaches the local file to the stated path in the Docker container.

Customising the configuration files

The same steps apply to custom configuration files as the Lua scripting. If you just want to add to the existing conf files rather than overwrite then ensure the name of your new file does not clash with pre-existing ones. This will automatically be included in the main nginx.conf.

To make edits to the config.json you can grab this file from your admin portal with the following URL: https://<account>-admin.3scale.net/admin/api/nginx/spec.json and copy & paste the contents locally. You can pass this local JSON file with the following command to start APIcast:

docker run --name apicast --rm -p 8080:8080 -v $(pwd)/path_to/config.json:/opt/app/config.json:ro -e THREESCALE_CONFIG_FILE=/opt/app/config.json

You should now be able to run APIcast on Docker. For other deployment options, check out the related articles.