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.
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 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
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.
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.
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.
<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:
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).