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 Releases 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 apicast-configuration-url-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
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.
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
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
:ro indicates that the volume will be read-only.
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
Here are some useful options that can be used with
docker run command:
--rmAutomatically remove the container when it exits
--detachRun 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.
--publishPublish a container's port to the host. The value should have the format
<host port>:<container port>, so
-p 80:8080will bind port
8080of the container to port
80of 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.
--envSet environment variables
--volumeMount a volume. The value is typically represented as
<host path>:<container path>[:<options>].
<options>is an optional attribute, it can be set to
:roto specify that the volume will be read only (it is mounted in read-write mode by default). Example:
See the Docker commands reference for more information on available options.
The gateway is able of checking the configuration from time to time and self update, you can enable this by adjusting the APICAST_CONFIGURATION_CACHE (seconds) to some value greater than 60:
This variable is set to 0 by default.
Signals are the same as normal NGINX.
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. On macOS you can run
brew bundleto install OpenResty and LuaRocks.
Install the APIcast development dependencies
- 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
Having dependency errors? Majority of the time the below will resolve it:
rm -rf lua_modules make dependencies
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:
To run just the unit tests:
To run just the integration tests:
To see additional test targets (such as testing produced Docker images) use:
Development using Docker
This option requires a single step:
That will create a Docker container and run bash inside it. This command will take care of installing all dependencies.
The project's source code will be available in the container and sync'ed with
apicast directory, so you can edit files in your preferred
environment and still be able to run whatever you need inside the Docker container.
To run the tests inside the container, just run:
For details on how to contribute to this repo see CONTRIBUTING
To build a release run:
make runtime-image IMAGE_NAME=apicast:release-name
Test the release:
make test-runtime-image IMAGE_NAME=apicast:release-name
Push the release to the registry (optional REGISTRY value, defaults to quay.io):
make push IMAGE_NAME=apicast:release-name