APIcast Self-Managed

This document refers to APIcast v1 which is currently available for download from the 3scale Admin Portal. For details on how to deploy APIcast v2, please see this guide.

This tutorial shows the necessary steps to deploy APIcast 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 package:

sudo yum install openresty

If you want to use APIcast v2, you will also need to install the resty command-line utility with the following command:

sudo yum install openresty-resty

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

Step 2: Deploy and run APIcast v1

Download the configuration files

To transform your NGINX (OpenResty) instance into a 3scale API gateway ready to use for your API, download your configuration files from your 3scale Admin Portal. You can find the link Download the NGINX Config files at the bottom of the Integration page for your API.

The downloaded proxy_configs.zip archive will contain the following files (XXX will be a numeric ID):

  • nginx_XXX.conf is an NGINX configuration file. You can customize it to meet you production environment requirements: set the number of worker processes, configure logging, etc. (check NGINX documentation for more information).
    You will also need to:

    • Check that the correct port is specified in the listen directive in the server block and change if needed.
    • If you want to use HTTPS on your APIcast instance, make the necessary changes in your NGINX configuration file – you can refer to the NGINX documentation for more details.
    • By default the lua_code_cache directive is set to off, which is useful for testing purposes. When you are ready to run the configuration in production, make sure to change this to on to improve the performance.
  • The nginx_XXX.lua file contains the logic that you defined in your Admin Portal (authentication methods, mapping rules etc.) You can modify the file to add new features or handle custom requirements that are not supported by 3scale Admin Portal web interface.

  • (Optional) If you have chosen OAuth as your authentication method, you'll also see other Lua files: authorize.lua, get_token.lua, etc. You can find more details about these files in the APIcast OAuth guide guide.

You will need to copy all the .conf and .lua files to the OpenResty configuration directory. If you installed OpenResty using the instructions in Step 1, the default path will be /usr/local/openresty/nginx/conf/.

Run APIcast

After you have copied the files, you can start APIcast by running:

sudo openresty -c /usr/local/openresty/nginx/conf/nginx_XXX.conf

You can also run a syntax error test on the configuration file by running the previous command with the -t parameter.

You can control the running NGINX by executing the same command with the parameter -s:

sudo openresty -c /usr/local/openresty/nginx/conf/nginx_XXX.conf -s SIGNAL

where SIGNAL is one of the following:

  • stop - fast shutdown
  • quit – graceful shutdown (waits for the worker processes to finish serving current requests)
  • reload – reloads the workers using the updated configuration file

The logs by default will be in the /usr/local/openresty/nginx/logs directory. If you have any problems with the setup, you might want to check the error.log for details. You can also check out the Troubleshooting guide for solutions to some common issues.

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.