APIcast v2 Self-Managed

This tutorial shows the necessary steps to deploy APIcast v2 on your own server to have it 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. Make sure Self-managed Gateway is selected as the deployment option in the integration settings. You should have both Staging and Production environment configured to proceed.

You should also have a server where you'll deploy APIcast self-managed. This tutorial covers how to install your self-managed APIcast instance on a server running Red Hat Enterprise Linux – the operating system supported by the Red Hat 3scale API management platform. The server can be located either in the cloud, or on premise.

Step 1: Install OpenResty and dependencies

APIcast requires some external modules for NGINX. Even though it’s possible to compile NGINX with these modules from source, we strongly recommend using OpenResty – an excellent bundle that already includes all the necessary modules.

This guide covers the steps to set up the official pre-built packages that OpenResty provides for Red Hat Enterprise Linux (RHEL) version 7. The latest installation instructions can be found in the OpenResty documentation.

For other operating systems please refer to the OpenResty installation instructions.

First, add the openresty repository to your RHEL system by creating the file /etc/yum.repos.d/OpenResty.repo with the following content:

name=Official OpenResty Repository

Install OpenResty and the resty command-line utility with the following command:

sudo yum install openresty openresty-resty

You can learn more about these and other OpenResty packages in OpenResty documentation.

APIcast v2 uses LuaRocks for managing Lua dependencies. As it's not in the standard Yum repositories, you must first enable the EPEL (Extra Packages for Enterprise Linux) package repository. Please refer to the following article on Red Hat Customer Portal for more information on how to enable EPEL on RHEL.

For RHEL 7 you can run the following command:

sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

Install LuaRocks:

sudo yum install luarocks

If you are using OAuth authentication method, please refer to APIcast v2 OAuth guide for more details on how to set it up.

Step 2: Deploy and run APIcast v2

In APIcast v2 the code that implements the gateway logic is separated from the configuration of your API. In order to deploy APIcast v2 to your server, you'll first need to get the APIcast code.

To use the latest APIcast version, you can check out the APIcast GitHub repository. If you want to use a specific version of APIcast, check the APIcast releases page.

Go to the apicast directory, that you checked out with git or extracted from the downloaded archive.

Run the following command to install all the Lua dependencies:

sudo luarocks make apicast/*.rockspec --tree /usr/local/openresty/luajit

You can start APIcast v2 using the bin/apicast executable included in the package.

THREESCALE_PORTAL_ENDPOINT=https://<ACCESS_TOKEN>@<DOMAIN>-admin.3scale.net bin/apicast

Here <ACCESS_TOKEN> is an Access Token (not a Service Token) for the 3scale Account Management API, and <DOMAIN>-admin.3scale.net is the URL of your 3scale Admin Portal.

This command will start APIcast v2 and download the latest APIcast configuration from the 3scale Admin Portal.

bin/apicast executable accepts a number of options, you can check them out by running:

bin/apicast -h

Additional parameters can be specified using environment variables.

APICAST_LOG_FILE=logs/error.log bin/apicast -c config.json -d -v -v -v

The above command will run APIcast as a daemon (-d option,) using the configuration file config.json, with the error logs at debug level (-v -v -v) and written to the logs/error.log file inside the apicast directory (the prefix directory).

And that's it! You should now be running APIcast Self-Managed. If you’re looking to install APIcast on OpenShift or using Docker, we recommend checking out those tutorials.