Skip to content

Running Docker NGINX‑based Image

The Wallarm NGINX-based filtering node can be deployed using a Docker image. This node supports both x86_64 and ARM64 processor operating systems, which are automatically identified during installation. This article provides guidance on how to run the node from the Docker image.

The Docker image is based on Alpine Linux and the NGINX version provided by Alpine. Currently, the latest image uses Alpine Linux version 3.20, which includes NGINX stable 1.26.2.

Use cases

Among all supported Wallarm deployment options, NGINX-based Docker image is recommended for Wallarm deployment in these use cases:

  • If your organization utilizes Docker-based infrastructure, Wallarm Docker image is the ideal choice. It integrates effortlessly into your existing setup, whether you are employing a microservice architecture running on AWS ECS, Alibaba ECS, or other similar services. This solution also applies to those using virtual machines seeking a more streamlined management through Docker containers.

  • If you require fine-grained control over each container, the Docker image excels. It affords a greater level of resource isolation than typically possible with traditional VM-based deployments.

For more information on running Wallarm's NGINX-based Docker image on popular public cloud container orchestration services, refer to our guides: AWS ECS, GCP GCE, Azure Container Instances, Alibaba ECS.

Requirements

  • Docker installed on your host system

  • Access to https://hub.docker.com/r/wallarm/node to download the Docker image. Please ensure the access is not blocked by a firewall

  • Access to the account with the Administrator role in Wallarm Console in the US Cloud or EU Cloud

  • Access to https://us1.api.wallarm.com if working with US Wallarm Cloud or to https://api.wallarm.com if working with EU Wallarm Cloud. Please ensure the access is not blocked by a firewall

  • Access to the IP addresses below for downloading updates to attack detection rules and API specifications, as well as retrieving precise IPs for your allowlisted, denylisted, or graylisted countries, regions, or data centers

    34.96.64.17
    34.110.183.149
    35.235.66.155
    34.102.90.100
    34.94.156.115
    35.235.115.105
    
    34.160.38.183
    34.144.227.90
    34.90.110.226
    

Options for running the container

The filtering node configuration parameters should be passed to the deployed Docker container in one of the following ways:

  • In the environment variables. This option allows for the configuration of only basic filtering node parameters. Most directives cannot be configured through environment variables.

  • In the mounted configuration file. This option allows full filtering node configuration via any directives. With this configuration method, environment variables with the filtering node and Wallarm Cloud connection settings are also passed to the container.

Run the container passing the environment variables

To run the container:

  1. Get Wallarm token of the appropriate type:

    1. Open Wallarm Console → SettingsAPI tokens in the US Cloud or EU Cloud.
    2. Find or create API token with the Deploy source role.
    3. Copy this token.
    1. Open Wallarm Console → Nodes in the US Cloud or EU Cloud.
    2. Do one of the following:
      • Create the node of the Wallarm node type and copy the generated token.
      • Use existing node group - copy token using node's menu → Copy token.
  2. Run the container with the node:

    docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -e NGINX_BACKEND='example.com' -e WALLARM_API_HOST='us1.api.wallarm.com' -p 80:80 wallarm/node:5.0.3-1
    
    docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -e NGINX_BACKEND='example.com' -p 80:80 wallarm/node:5.0.3-1
    

You can pass the following basic filtering node settings to the container via the option -e:

Environment variable Description Required
WALLARM_API_TOKEN Wallarm node or API token. Yes
WALLARM_LABELS

Available starting from node 4.6. Works only if WALLARM_API_TOKEN is set to API token with the Deploy role. Sets the group label for node instance grouping, for example:

WALLARM_LABELS="group=<GROUP>"

...will place node instance into the <GROUP> instance group (existing, or, if does not exist, it will be created).

Yes (for API tokens)
NGINX_BACKEND Domain or IP address of the resource to protect with the Wallarm solution. Yes
WALLARM_API_HOST Wallarm API server:
  • us1.api.wallarm.com for the US Cloud
  • api.wallarm.com for the EU Cloud
By default: api.wallarm.com.
No
WALLARM_MODE Node mode:
  • block to block malicious requests
  • safe_blocking to block only those malicious requests originated from graylisted IP addresses
  • monitoring to analyze but not block requests
  • off to disable traffic analyzing and processing
By default: monitoring.
Detailed description of filtration modes →
No
WALLARM_APPLICATION Unique identifier of the protected application to be used in the Wallarm Cloud. The value can be a positive integer except for 0.

Default value (if the variable is not passed to the container) is -1 which indicates the default application displayed in Wallarm Console → Settings → Application.

More details on setting up applications →
No
TARANTOOL_MEMORY_GB Amount of memory allocated to Tarantool. The value can be an integer or a float (a dot . is a decimal separator). By default: 1 gygabytes. No
NGINX_PORT Sets a port that NGINX will use inside the Docker container.

Starting from the Docker image 4.0.2-1, the wallarm-status service automatically runs on the same port as NGINX.

Default value (if the variable is not passed to the container) is 80.

Syntax is NGINX_PORT='443'.
No
WALLARM_STATUS_ALLOW Custom CIDRs that are allowed to access the /wallarm-status endpoint from outside the Docker container. Example value: 10.0.0.0/8. If you need to pass several values, use a comma , as a separator. To access the service externally, use the Docker container's IP, specifying the /wallarm-status endpoint path. No
DISABLE_IPV6 The variable with any value except for an empty one deletes the listen [::]:80 default_server ipv6only=on; line from the NGINX configuration file which will stop NGINX from IPv6 connection processing.

If the variable is not specified explicitly or has an empty value "", NGINX processes both IPv6 and IPv4 connections.
No
WALLARM_APIFW_ENABLE This setting toggles API Specification Enforcement on or off, available from release 4.10 onwards. Please note that activating this feature does not substitute for the required subscription and configuration through the Wallarm Console UI.

Its default value is true, enabling the functionality.
No

The command does the following:

  • Creates the file default with minimal NGINX configuration and passes filtering node configuration in the /etc/nginx/sites-enabled container directory.

  • Creates files with filtering node credentials to access the Wallarm Cloud in the /opt/wallarm/etc/wallarm container directory:

    • node.yaml with filtering node UUID and secret key
    • private.key with Wallarm private key
  • Protects the resource http://NGINX_BACKEND:80.

Run the container mounting the configuration file

You can mount the prepared configuration file to the Docker container via the -v option. The file must contain the following settings:

To run the container:

  1. Get Wallarm token of the appropriate type:

    1. Open Wallarm Console → SettingsAPI tokens in the US Cloud or EU Cloud.
    2. Find or create API token with the Deploy source role.
    3. Copy this token.
    1. Open Wallarm Console → Nodes in the US Cloud or EU Cloud.
    2. Do one of the following:
      • Create the node of the Wallarm node type and copy the generated token.
      • Use existing node group - copy token using node's menu → Copy token.
  2. Run the container with the node:

    docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -e WALLARM_API_HOST='us1.api.wallarm.com' -v /configs/default:/etc/nginx/sites-enabled/default -p 80:80 wallarm/node:5.0.3-1
    
    docker run -d -e WALLARM_API_TOKEN='XXXXXXX' -e WALLARM_LABELS='group=<GROUP>' -v /configs/default:/etc/nginx/sites-enabled/default -p 80:80 wallarm/node:5.0.3-1
    
    • The -e option passes the following required environment variables to the container:

      Environment variable Description Required
      WALLARM_API_TOKEN Wallarm node or API token. Yes
      WALLARM_API_HOST Wallarm API server:
      • us1.api.wallarm.com for the US Cloud
      • api.wallarm.com for the EU Cloud
      By default: api.wallarm.com.
      No
      WALLARM_LABELS

      Available starting from node 4.6. Works only if WALLARM_API_TOKEN is set to API token with the Deploy role. Sets the group label for node instance grouping, for example:

      WALLARM_LABELS="group=<GROUP>"

      ...will place node instance into the <GROUP> instance group (existing, or, if does not exist, it will be created).

      Yes (for API tokens)
    • The -v option mounts the directory with the configuration file default to the /etc/nginx/sites-enabled container directory.

      See an example of the mounted file with minimal settings
      server {
              listen 80 default_server;
              listen [::]:80 default_server ipv6only=on;
              #listen 443 ssl;
      
              server_name localhost;
      
              #ssl_certificate cert.pem;
              #ssl_certificate_key cert.key;
      
              root /usr/share/nginx/html;
      
              index index.html index.htm;
      
              wallarm_mode monitoring;
      
              location / {
      
                      proxy_pass http://example.com;
                      include proxy_params;
              }
      }
      

      Mounting other configuration files

      The container directories used by NGINX:

      • /etc/nginx/nginx.conf - This is the main NGINX configuration file. If you decide to mount this file, additional steps are necessary for proper Wallarm functionality:

        1. In nginx.conf, add the following setting at the top level:

          include /etc/nginx/modules-enabled/*.conf;
          
        2. In nginx.conf, add the wallarm_srv_include /etc/nginx/wallarm-apifw-loc.conf; directive in the http block. This specifies the path to the configuration file for API Specification Enforcement.

        3. Mount the wallarm-apifw-loc.conf file to the specified path. The content should be:

          location ~ ^/wallarm-apifw(.*)$ {
                  wallarm_mode off;
                  proxy_pass http://127.0.0.1:8088$1;
                  error_page 404 431         = @wallarm-apifw-fallback;
                  error_page 500 502 503 504 = @wallarm-apifw-fallback;
                  allow 127.0.0.0/8;
                  deny all;
          }
          
          location @wallarm-apifw-fallback {
                  wallarm_mode off;
                  return 500 "API FW fallback";
          }
          
        4. Mount the /etc/nginx/conf.d/wallarm-status.conf file, ensuring its contents align with the template.

        5. Within the NGINX configuration files, set up the configuration for the /wallarm-status service according to the template.
      • /etc/nginx/conf.d — common settings

      • /etc/nginx/sites-enabled — virtual host settings
      • /opt/wallarm/usr/share/nginx/html — static files

      If required, you can mount any files to the listed container directories. The filtering node directives should be described in the /etc/nginx/sites-enabled/default file.

The command does the following:

  • Mounts the file default into the /etc/nginx/sites-enabled container directory.

  • Creates files with filtering node credentials to access Wallarm Cloud in the /opt/wallarm/etc/wallarm container directory:

    • node.yaml with filtering node UUID and secret key
    • private.key with Wallarm private key
  • Protects the resource http://example.com.

Logging configuration

The logging is enabled by default. The log directories are:

Monitoring configuration

To monitor the filtering node, there are Nagios‑compatible scripts inside the container. See details in Monitoring the filtering node.

Example of running the scripts:

docker exec -it <WALLARM_NODE_CONTAINER_ID> /usr/lib/nagios/plugins/check_wallarm_tarantool_timeframe -w 1800 -c 900
docker exec -it <WALLARM_NODE_CONTAINER_ID> /usr/lib/nagios/plugins/check_wallarm_export_delay -w 120 -c 300
  • <WALLARM_NODE_CONTAINER_ID> is the ID of the running Wallarm Docker container. To get the ID, run docker ps and copy the proper ID.

Testing Wallarm node operation

  1. Send the request with test Path Traversal attack to a protected resource address:

    curl http://localhost/etc/passwd
    
  2. Open Wallarm Console → Attacks section in the US Cloud or EU Cloud and make sure the attack is displayed in the list.
    Attacks in the interface

Configuring the use cases

The configuration file mounted to the Docker container should describe the filtering node configuration in the available directive. Below are some commonly used filtering node configuration options: