3scale api gateway reloaded
Lua Perl Shell Makefile Nginx Perl6 Ruby
Latest commit fc07d79 Jan 20, 2017 @mayorova mayorova committed on GitHub Merge pull request #162 from 3scale/oauth-use-authorization-header
Use Authorization: Bearer xyz header for calls using OAuth
Failed to load latest commit information.
.github [doc] fix documentation after v2 branch removal Jan 10, 2017
apicast [balancer] extract select_peer method Jan 20, 2017
bin [http_ng] import apitools http_ng client Jan 13, 2017
doc Change v2 to master in parameters doc Jan 10, 2017
examples [examples] echo api example Jan 17, 2017
fixtures [lua] skeleton of configuration object Aug 18, 2016
openshift [RHAMP-41] ability to set REDIS_HOST from the OpenShift Template Jan 13, 2017
script balancer_by_lua prototype Oct 24, 2016
spec [balancer] extract select_peer method Jan 20, 2017
t OAuth tests for extracting credentials from headers Jan 20, 2017
travis [travis] upgrade s2i Jan 20, 2017
.busted preload ffi modules in busted Oct 24, 2016
.codeclimate.yml adding codeclimate related code Jul 12, 2016
.env [conf] allow customizing curl timeout Nov 17, 2016
.gitignore [doc] integrate tool to check broken links in the documentation Jan 10, 2017
.lgtm [lgtm] configure lgtm approvals Sep 5, 2016
.luacheckrc [http_ng] import apitools http_ng client Jan 13, 2017
.luacov run luacov Aug 21, 2016
.mailmap .mailmap: map authors to their names/addresses Nov 22, 2016
.travis.yml [travis] upgrade s2i Jan 20, 2017
3scale-gateway-openshift-template.yml rename to APIcast Oct 3, 2016
3scale-portal-endpoint-secret.yml rename to APIcast Oct 3, 2016
CHANGELOG.md [travis] bump s2i-openresty Jan 20, 2017
LICENSE Change license file to have contents of Apache2.0 license Nov 25, 2016
Makefile Merge pull request #239 from 3scale/travis-s2i Jan 20, 2017
NOTICE Add NOTICE Nov 25, 2016
README.md Merge pull request #209 from 3scale/master-docs Jan 10, 2017
cpanfile [test] use perl Carton to lock test dependencies Aug 30, 2016
cpanfile.snapshot [travis] do not upload cache of cpan Sep 28, 2016
docker-compose.yml load nameservers from /etc/resolver.conf Oct 24, 2016
openresty.repo Install openresty using the official RPM's Sep 2, 2016
rockspec [ldoc] integrate ldoc Jan 5, 2017
schema.json minimal json schema specification for the config Sep 12, 2016


APIcast is an NGINX based API gateway used to integrate your internal and external API services with 3scale’s API Management Platform.

To learn more about deployment options, environments provided, and how to get started, go to the APIcast overview.


master branch is not stable and not recommended for production use. For the latest release, go to Relases page.


This Dockerfile creates a 3scale gateway, and configures itself according to your 3scale params.


To run APIcast on OpenShift, just use template and create a Secret to point to your 3scale Admin Portal.

oc secret new-basicauth threescale-portal-endpoint-secret --password=https://ACCESS-TOKEN@ACCOUNT-admin.3scale.net
oc new-app -f https://raw.githubusercontent.com/3scale/apicast/master/openshift/apicast-template.yml


You can download a ready to use Docker image from our repository:

docker pull quay.io/3scale/apicast:master

The 3scale gateway image requires one of two environment variables. The first option will pull the latest gateway configuration from the 3scale API Manager. The second points to a local configuration file which has already been downloaded from 3scale:


URI that includes your password and portal endpoint in following format: schema://access-token@domain. The password can be either the provider key or an access token for the 3scale Account Management API. Note: these should not be confused with service tokens Example: https://ACCESS-TOKEN@ACCOUNT-admin.3scale.net (where the host name is the same as the domain for the URL when you are logged into the admin portal from a browser.

When THREESCALE_PORTAL_ENDPOINT environment variable is provided, the gateway will download the configuration from the 3scale on initializing. The configuration includes all the settings provided on the Integration page of the API(s).

docker run --name apicast --rm -p 8080:8080 -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS-TOKEN@ACCOUNT-admin.3scale.net quay.io/3scale/apicast:master

Path to saved JSON file with configuration for the gateway. The configuration can be downloaded from the 3scale admin portal using the URL https://ACCOUNT-admin.3scale.net/admin/api/nginx/spec.json (replace ACCOUNT with your 3scale account name). The file has to be injected to the docker image as read only volume, and the path should indicate where the volume is mounted, i.e. path local to the docker container.

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

In this example config.json is located in the same directory where the docker command is executed, and it is mounted as a volume at /opt/app/config.json. :ro indicates that the volume will be read-only.

The JSON file needs to follow the schema, see an example file with the fields that are used by the gateway.

In some 3scale plans it is possible to create multiple API services (see an example of the configuration file). The optional APICAST_SERVICES environment variable allows filtering the list of services, so that the gateway only includes the services explicitly specified, the value of the variable should be a comma-separated list of service IDs. This setting is useful when you have many services configured on 3scale, but you want to expose just a subset of them in the gateway.

docker run --name apicast --rm -p 8080:8080 -e THREESCALE_PORTAL_ENDPOINT=https://ACCESS-TOKEN@ACCOUNT-admin.3scale.net -e APICAST_SERVICES=1234567890987 quay.io/3scale/apicast:master

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 commands reference for more information on available options.

Auto updating

The gateway is able of checking the configuration from time to time and self update, you can enable this by adjusting the AUTO_UPDATE_INTERVAL (seconds) to some value greater than 60:


This variable is set to 0 by default.


Signals are the same as normal NGINX.

Use docker kill -s $SIGNAL CONTAINER to send them, where CONTAINER is the container ID or name.

Development & Testing

Tools and dependencies

For developing and testing APIcast the following tools are needed:

  • OpenResty - a bundle based on NGINX core and including LuaJIT and Lua modules. Follow the installation instructions according to your OS.

  • LuaRocks - the Lua package manager. You can find installation instructions for different platforms in the documentation. For Mac OS X the following Homebrew formula can be used:

    brew install apitools/openresty/luarocks
  • busted - unit testing framework, used for unit testing.

    luarocks install busted
  • Test::Nginx – used for integration testing.

    cpan install Carton
    cpan install Test::Nginx
  • redis in-memory data store is used for caching. The tests for the OAuth flow require a redis instance running on localhost.

  • Docker and s2i

    There are tests that run in Docker container, to execute these Docker needs to be installed, and to build the images Source-To-Image is used. To install it, download it from the releases page, and put the extracted s2i executable on your PATH.

Running the tests

To run all the tests at once, execute:

make test

To run just the unit tests:

make busted

To run just the integration tests:

make prove

To see additional test targets (such as testing produced Docker images) use:

make help


For details on how to contribute to this repo see CONTRIBUTING