Chapter 3. APIcast Self-Managed

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 also have a server where you’ll deploy your API gateway(s). 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.

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:

[openresty]
name=Official OpenResty Repository
baseurl=https://copr-be.cloud.fedoraproject.org/results/openresty/openresty/epel-7-$basearch/
skip_if_unavailable=True
gpgcheck=1
gpgkey=https://copr-be.cloud.fedoraproject.org/results/openresty/openresty/pubkey.gpg
enabled=1
enabled_metadata=1

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 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 OAuth guide for more details on how to set it up.

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

To use the latest stable 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 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 for the 3scale Account Management API, and <domain>-admin.3scale.net is the URL of your 3scale Admin Portal.

This command will start APIcast 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 the Docker containerized environment, we recommend checking out those tutorials.