Running API Firewall on Docker¶
This guide walks through downloading, installing, and starting Wallarm API Firewall on Docker.
OpenAPI 3.0 specification developed for the REST API of the application that should be protected with Wallarm API Firewall
Step 1. Create the Docker network¶
To allow the containerized application and API Firewall communication without manual linking, create a separate Docker network by using the command
docker network create. The application and API Firewall containers will be linked to this network.
For example, to create the Docker network named
docker network create api-firewall-network
Step 2. Start the containerized application¶
Start the containerized application that should be protected with API Firewall by using the command
docker run and passing the created network name in the option
docker run --rm -it --network api-firewall-network \ --network-alias backend -p 8090:8090 kennethreitz/httpbin
Step 3. Start API Firewall¶
Start the pulled API Firewall image by using the command
docker run and passing API Firewall configuration in the environment variables as described below.
docker run --rm -it --network api-firewall-network --network-alias api-firewall \ -v <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC> -e APIFW_API_SPECS=<PATH_TO_MOUNTED_SPEC> \ -e APIFW_URL=<API_FIREWALL_URL> -e APIFW_SERVER_URL=<PROTECTED_APP_URL> \ -e APIFW_REQUEST_VALIDATION=<REQUEST_VALIDATION_MODE> -e APIFW_RESPONSE_VALIDATION=<RESPONSE_VALIDATION_MODE> \ -p 8088:8088 wallarm/api-firewall:v0.6.4
-v option, please mount the OpenAPI 3.0 specification to the API Firewall container directory:
HOST_PATH_TO_SPEC: the path to the OpenAPI 3.0 specification for your application REST API located on the host machine. The accepted file formats are YAML and JSON (
.jsonfile extensions). For example:
<CONTAINER_PATH_TO_SPEC>: the path to the container directory to mount the OpenAPI 3.0 specification to. For example:
-e option, please set the API Firewall configuration through the following environment variables:
| ||Path to the OpenAPI 3.0 specification mounted to the container. For example: ||Yes|
| ||URL for API Firewall. For example: |
If API Firewall listens to the HTTPS protocol, please mount the generated SSL/TLS certificate and private key to the container, and pass to the container the API Firewall SSL/TLS settings described below.
| ||URL of the application described in the mounted OpenAPI specification that should be protected with API Firewall. For example: ||Yes|
| ||API Firewall mode when validating requests sent to the application URL: ||Yes|
| ||API Firewall mode when validating application responses to incoming requests: ||Yes|
| ||API Firewall logging level. Possible values: ||No|
| ||HTTP response status code returned by API Firewall operating in the ||No|
|Whether to return the header ||No|
| ||The format of API Firewall logs. The value can be ||No|
(only if API Firewall is operating in the
|HTTP response status codes indicating that the requested API endpoint that is not included in the specification is NOT a shadow one. You can specify several status codes separated by a semicolon (e.g. |
By default, API Firewall operating in the
|API Firewall SSL/TLS settings|
| ||The path to the container directory with the mounted certificate and private key generated for API Firewall.||No|
| ||The name of the file with the SSL/TLS certificate generated for API Firewall and located in the directory specified in ||No|
| ||The name of the file with the SSL/TLS private key generated for API Firewall and located in the directory specified in ||No|
| ||The timeout for API Firewall to read the full request (including body) sent to the application URL. The default value is ||No|
| ||The timeout for API Firewall to return the response to the request sent to the application URL. The default value is ||No|
| ||The maximum number of connections that API Firewall can handle simultaneously. The default value is ||No|
| ||The timeout for API Firewall to read the full response (including body) returned to the request by the application. The default value is ||No|
| ||The timeout for API Firewall to write the full request (including body) to the application. The default value is ||No|
| ||The timeout for API Firewall to connect to the application. The default value is ||No|
Step 4. Test API Firewall operation¶
To test API Firewall operation, send the request that does not match the mounted Open API 3.0 specification to the API Firewall Docker container address. For example, you can pass the string value in the parameter that requires the integer value.
If the request does not match the provided API schema, the appropriate ERROR message will be added to the API Firewall Docker container logs.
Step 5. Enable traffic on API Firewall¶
To finalize the API Firewall configuration, please enable incoming traffic on API Firewall by updating your application deployment scheme configuration. For example, this would require updating the Ingress, NGINX, or load balancer settings.