Running API Firewall on Docker for REST API¶
This guide walks through downloading, installing, and starting Wallarm API Firewall on Docker for REST API request validation.
OpenAPI 3.0 specification developed for the REST API of the application that should be protected with Wallarm API Firewall
Methods to run API Firewall on Docker¶
The fastest method to deploy API Firewall on Docker is Docker Compose. The steps below rely on using this method.
If required, you can also use
docker run. We have provided proper
docker run commands to deploy the same environment in this section.
Step 1. Create the
To deploy API Firewall and proper environment using Docker Compose, create the docker-compose.yml with the following content first:
version: '3.8' networks: api-firewall-network: name: api-firewall-network services: api-firewall: container_name: api-firewall image: wallarm/api-firewall:v0.6.14 restart: on-failure volumes: - <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC> environment: APIFW_API_SPECS: <PATH_TO_MOUNTED_SPEC> APIFW_URL: http://0.0.0.0:8088/ APIFW_SERVER_URL: <PROTECTED_APP_URL> APIFW_REQUEST_VALIDATION: <REQUEST_VALIDATION_MODE> APIFW_RESPONSE_VALIDATION: <RESPONSE_VALIDATION_MODE> ports: - "8088:8088" stop_grace_period: 1s networks: - api-firewall-network backend: container_name: api-firewall-backend image: kennethreitz/httpbin restart: on-failure ports: - 8090:8090 stop_grace_period: 1s networks: - api-firewall-network
Step 2. Configure the Docker network¶
If required, change the Docker network configuration defined in docker-compose.yml →
The provided docker-compose.yml instructs Docker to create the network
api-firewall-network and link the application and API Firewall containers to it.
It is recommended to use a separate Docker network to allow the containerized application and API Firewall communication without manual linking.
Step 3. Configure the application to be protected with API Firewall¶
Change the configuration of the containerized application to be protected with API Firewall. This configuration is defined in docker-compose.yml →
The provided docker-compose.yml instructs Docker to start the kennethreitz/httpbin Docker container connected to the
api-firewall-network and assigned with the
backend network alias. The container port is 8090.
If configuring your own application, define only settings required for the correct application container start. No specific configuration for API Firewall is required.
Step 4. Configure API Firewall¶
Pass API Firewall configuration in docker-compose.yml →
services.api-firewall as follows:
services.api-firewall.volumes, 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:
services.api-firewall.environment, please set the general API Firewall configuration through the following environment variables:
| ||Path to the OpenAPI 3.0 specification. There are the following ways to specify the path: ||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.
The default value is
| ||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|
| ||If it is set to ||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
| ||Sets the general API Firewall mode. Possible values are ||No|
| ||When set to ||No|
| ||This specifies whether requests are identified as non-matching the specification if their parameters do not align with those defined in the OpenAPI specification. The default value is |
If running API Firewall in the
services.api-firewall.networks, set the API Firewall container port and connect the container to the created network. The provided docker-compose.yml instructs Docker to start API Firewall connected to the
api-firewall-network network on the port 8088.
Step 5. Deploy the configured environment¶
To build and start the configured environment, run the following command:
docker-compose up -d --force-recreate
To check the log output:
docker-compose logs -f
Step 6. 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 7. 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.
Stopping the deployed environment¶
To stop the environment deployed using Docker Compose, run the following command:
docker run to start API Firewall¶
To start API Firewall on Docker, you can also use regular Docker commands as in the examples below:
To create a separate Docker network to allow the containerized application and API Firewall communication without manual linking:
docker network create api-firewall-network
To start the containerized application to be protected with API Firewall:
docker run --rm -it --network api-firewall-network \ --network-alias backend -p 8090:8090 kennethreitz/httpbin
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.14
When the environment is started, test it and enable traffic on API Firewall following steps 6 and 7.