Skip to content
Sample code for building an API gateway with Docker
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


An API gateway is a single entry point for APIs in a microservices infrastructure. It provides authentication and authorization layers, routes and load balances requests to API services, and caches previous requests.

This sample code demonstrates how to deploy an API gateway with Docker and 3scale. There is no Docker image, you will need to amend the configuration files in conf according to your own 3scale configuration. These configuration files contain comments in uppercase starting with 'CHANGE' in order to highlight what you need to change.

Build the Docker image with:

docker build -t api-gateway .

Run the Docker container with:

docker run -p 80:80 -p 443:443 -d -it api-gateway

My 3scale configuration is set up with app_id and app_key as authentication mode.

Test it on port 80 with:

curl -v "" -H'app_id: your3scaleappid' -H'app_key: your3scaleappkey'

Test it on port 443 and https with:

curl -v "" -H'app_id: your3scaleappid' -H'app_key: your3scaleappkey'

3scale Settings

The configuration files in conf require settings which are specific to 3scale. Here is where to find the values for these settings on your 3scale admin account:


You can find your 3scale provider key in

alt text


You can find your API service ID by going to and selecting the API service:

alt text


If you set up a secret token in the API's authentication settings, you can find the secret token in (replace the dummy digits in the URL with your API service ID)

alt text


You can find the name of the .lua file by downloading the nginx configuration files from (replace the dummy digits in the URL with your API service ID). Make sure you first selected nginx On-premises Gateway in the Integration tab.

alt text

SSL Certificates

If you want to run the API gateway with HTTPS (recommended for production), put your .crt and .key certificates in certificates and make sure the file names are correctly set in the server directive of the nginx conf file, e.g.:

ssl_certificate /usr/local/openresty/nginx/ssl/bundle.crt;
ssl_certificate_key /usr/local/openresty/nginx/ssl/certificate.key;

You can create a self-signed SSL certificate using openssl (see also these instructions):

sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/ssl/nginx.key -out /etc/nginx/ssl/nginx.crt

If you are using a self-signed certificate, add -k to the curl command.

You can validate your SSL certificates using a Certificate Authority. Alternatively, you can validate them for free using Let's Encrypt.

If you want to force the use of HTTPS, remove the configuration for port 80 in the Dockerfile and nginx conf file.


If you have problems in running the API gateway, the best way to debug it is to look at the nginx logs. If you can't start nginx, run the Docker container without the -d flag:

docker run -p 80:80 -p 443:443 -it api-gateway

If you can start the Docker container but nginx throws errors at you, get inside the container with:

docker exec -it <container_name> /bin/bash

and inspect the logs at /usr/local/openresty/nginx/logs.


All secrets, passwords, certificates in this repository are clearly dummy. It is a bad security practice to store sensitive files under version control. Instead you can set up environment variables on your server and read them in your code so that sensitive information is replaced by placeholders (e.g. $SECRET). This approach is still not super secure but it is much better than storing secrets under version control. Alternatively, you can encrypt the sensitive information and make sure that your code decrypts it (for this approach see for example Ansible Vault).

You can’t perform that action at this time.