From 6bb8bd86fb2a89ea077038d82277ce20d5e73622 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 21 Oct 2025 15:53:57 +0100 Subject: [PATCH 1/3] feat: Updating linting tools and documentation This commit updates the Markdown linting configuration files, and adds an explanation of the linting available in the repository to the process documentation. The linter itself has been used on multiple files also affected in this commit There are a handful of peripheral changes made in the PR: - Adding the latest catalogue tags to the Hugo archetype metadata - Fixing a broken link for NGINX Amplify - Fixing duplicate tabs caused by includes (Closes #1343) - Adding reload instructions to NGINX configuration (Closes #1346) --- .gitlint | 2 +- .markdownlint.yaml | 58 ++++--- .pre-commit-config.yaml | 6 +- archetypes/concept.md | 5 +- archetypes/default.md | 6 +- archetypes/landing-page.md | 4 +- archetypes/tutorial.md | 21 ++- .../overview/overview-main-components.md | 2 +- .../waf/install-update-configuration.md | 7 +- content/waf/install/docker.md | 152 +++++------------- content/waf/install/virtual-environment.md | 108 +------------ documentation/linting-tools.md | 43 +++++ documentation/pre-commit.md | 32 +++- 13 files changed, 172 insertions(+), 274 deletions(-) create mode 100644 documentation/linting-tools.md diff --git a/.gitlint b/.gitlint index c776e9dbb..03a77d3f7 100644 --- a/.gitlint +++ b/.gitlint @@ -3,7 +3,7 @@ ignore = body-is-missing contrib = contrib-title-conventional-commits [title-max-length] -line-length = 50 +line-length = 60 [title-min-length] min-length = 5 diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 8ed0d233d..85d36b083 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,42 +1,40 @@ -default: true +# markdownlint enables all rules by default +# Setting default to false means that rules are +# instead enabled on a case-by-case basis +default: false -MD002: false +# Heading levels should only increment by one level at a time +MD001: true -MD003: false +# Detects if link brackets are in the wrong order: ()[] +MD011: true -MD004: - style: dash +# No multiple consecutive blank lines +MD012: true -MD009: false +# Headings should be surrounded by blank lines +MD022: true -MD010: false +# Headings must start at the beginning of a line +MD023: true -MD012: false +# No trailing punctuation in headings +MD026: true -MD013: - line_length: 5000 - heading_line_length: 60 - code_block_line_length: 80 - code_blocks: true - tables: false - headings: true - headers: true - strict: false - stern: false +# Code blocks should be surrounded by blank lines +MD031: true -MD022: false +# Lists should be surrounded by blank lines +MD032: true -MD024: - siblings_only: true +# Emphasis should not be used instead of headings +MD036: true -MD029: false +# No spaces on the outside of link text +MD039: true -MD033: false +# All images should have alt text +MD045: true -MD034: false - -MD041: false - -MD046: false - -MD051: false \ No newline at end of file +# Tables shou ld be surrounded by blank lines +MD058: true \ No newline at end of file diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index d48d49e18..8f91396aa 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -4,9 +4,13 @@ default_install_hook_types: repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v5.0.0 + rev: v6.0.0 hooks: - id: no-commit-to-branch +- repo: https://github.com/DavidAnson/markdownlint-cli2 + rev: v0.18.1 + hooks: + - id: markdownlint-cli2 - repo: https://github.com/jorisroovers/gitlint rev: v0.19.1 hooks: diff --git a/archetypes/concept.md b/archetypes/concept.md index b72f32b60..6ef0b90ee 100644 --- a/archetypes/concept.md +++ b/archetypes/concept.md @@ -8,7 +8,7 @@ toc: false # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this nd-content-type: concept # Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +# AGE, DOS, NAZ, NGC, NGF, NIC, NIM, NGF, ONE, NOS, NPL, SOL, WAF nd-product: --- @@ -42,7 +42,7 @@ It is an example of a , and is closely related to # Read their documentation for usage: https://mermaid.js.org/intro/ ``` -Starting from the of the diagram, you can see that is connected to : this relationship is established when configuring as part of . +Starting from the \ of the diagram, you can see that \ is connected to \: this relationship is established when configuring \ as part of \. [//]: # "End a particular use case section with links to other pages, such as instructional documentation, other concepts, or reference information (Such as API specifications)." @@ -52,7 +52,6 @@ Starting from the of the diagram, you can see that is connect ### Use case 2 - ## Conclusion [//]: # "Summarize everything that the reader will have learned by reading this entire concept document." diff --git a/archetypes/default.md b/archetypes/default.md index ba9cf1281..5e58d6feb 100644 --- a/archetypes/default.md +++ b/archetypes/default.md @@ -8,7 +8,7 @@ toc: false # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this nd-content-type: how-to # Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +# AGE, DOS, NAZ, NGC, NGF, NIC, NIM, NGF, ONE, NOS, NPL, SOL, WAF nd-product: --- @@ -39,6 +39,7 @@ To complete this guide, you will need the following prerequisites: ```shell # We typically show examples of commands or code in one code block, which can be easily copied by a reader using a button connected to the block. ``` + ```text # A second code block is used underneath the first to show what kind of example output to expect from the command. Truncate unnecessary output with ellipses (...). ``` @@ -57,17 +58,14 @@ To complete this guide, you will need the following prerequisites: ### Sub-step 1 - ### Sub-step 2 - ## Step 3 [//]: # "The final step of a how-to guide is usually a final test, and summarizes all of the previous steps taken to accomplish the purpose of the guide." ### Sub-step 1 - ### Sub-step 2 ## Next steps diff --git a/archetypes/landing-page.md b/archetypes/landing-page.md index be1cca187..184527cf6 100644 --- a/archetypes/landing-page.md +++ b/archetypes/landing-page.md @@ -14,11 +14,12 @@ nd-landing-page: true # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this nd-content-type: landing-page # Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +# AGE, DOS, NAZ, NGC, NGF, NIC, NIM, NGF, ONE, NOS, NPL, SOL, WAF nd-product: --- ## About + [//]: # "These are Markdown comments to guide you through document structure. Remove them as you go, as well as any unnecessary sections." [//]: # "Use underscores for _italics_, and double asterisks for **bold**." [//]: # "Backticks are for `monospace`, used sparingly and reserved mostly for executable names - they can cause formatting problems. Avoid them in tables: use italics instead." @@ -27,6 +28,7 @@ nd-product: [//]: # "Name specific functionality it provides: avoid ambiguous descriptions such as 'enables efficiency', focus on what makes it unique." ## Featured content + [//]: # "You can add a maximum of three cards: any extra will not display." [//]: # "One card will take full width page: two will take half width each. Three will stack like an inverse pyramid." [//]: # "Some examples of content could be the latest release note, the most common install path, and a popular new feature." diff --git a/archetypes/tutorial.md b/archetypes/tutorial.md index 1190e6072..a9ae12e45 100644 --- a/archetypes/tutorial.md +++ b/archetypes/tutorial.md @@ -8,7 +8,7 @@ toc: false # Types have a 1:1 relationship with Hugo archetypes, so you shouldn't need to change this nd-content-type: tutorial # Intended for internal catalogue and search, case sensitive: -# Agent, N4Azure, NIC, NIM, NGF, NAP-DOS, NAP-WAF, NGINX One, NGINX+, Solutions, Unit +# AGE, DOS, NAZ, NGC, NGF, NIC, NIM, NGF, ONE, NOS, NPL, SOL, WAF nd-product: --- @@ -18,16 +18,16 @@ nd-product: [//]: # "Begin each document with a sentence or two explaining what the purpose of the guide is, and what high-level actions to expect. No need to adhere precisely the example text given anywhere in this template." -This guide is a tutorial on how to set up . While going through the steps of this tutorial, , and will be introduced and explained to understand how works. +This guide is a tutorial on how to set up \. While going through the steps of this tutorial, \, \ and \ will be introduced and explained to understand how \ works. -By the end of the tutorial, you should have enough working knowledge of to develop your own . +By the end of the tutorial, you should have enough working knowledge of \ to develop your own \. ## Background [//]: # "The largest difference between a tutorial and a how-to document is the scope of detail included. While working on the tutorial, consider what overlap might exist with a concept document." [//]: # "We want to reduce the amount of context switching a reader has to go through, so it might be beneficial to convert some text content into an include for re-use between a tutorial and a concept document." - is a common use for : it enables the ability to use , and , which are important when configuring for . +\ is a common use for \: it enables the ability to use \, \ and \, which are important when configuring \ for \. ## Before you begin @@ -46,7 +46,7 @@ To complete this guide, you will need the following prerequisites: [//]: # "The text immediately following a heading in a tutorial should likely explain a concept to build a mental model of what the reader is about to do." [//]: # "If it's a successive step (One after the first), you might refer to work already done to follow the sequence of operations." -The first thing required for setting up is . This is the that the will run on. The that is set-up from this step is necessary for , and will be connected to and in a later step. The we are configuring will look something along the lines of this by the end: +The first thing required for setting up \ is \. This is the \ that the \ will run on. The \ that is set-up from this step is necessary for \, and will be connected to \ and \ in a later step. The \ we are configuring will look something along the lines of this by the end: [//]: # "If it helps, include a diagram of some kind. Ensure your description provides all the context required, however: a diagram is an aid to explain things, not a replacement." @@ -55,7 +55,7 @@ The first thing required for setting up is . This is the of the diagram, you can see that is connected to : this relationship is established when configuring as part of . +Starting from the \ of the diagram, you can see that \ is connected to \: this relationship is established when configuring \ as part of \. ### Sub-step 1 @@ -63,20 +63,22 @@ Starting from the of the diagram, you can see that is connect [//]: # "Though there may be multiple ways to accomplish a task, focus on showing the reader the exact way to do one." [//]: # "You can mention alternative paths, but do not give unnecessary detail: it detracts from the task at hand." -To set up , start by running the following command. It will create : take note of the value, as it will be used for connecting in later steps. +To set up \, start by running the following command. It will create \: take note of the \ value, as it will be used for connecting \ in later steps. ```shell # We typically show examples of commands or code in one code block, which can be easily copied by a reader using a button connected to the block. ``` + ```text # A second code block is used underneath the first to show what kind of example output to expect from the command. Truncate unnecessary output with ellipses (...). ``` -To verify the creation of , you can also inspect information about it using . The output should look something like this: +To verify the creation of \, you can also inspect information about it using \. The output should look something like this: ```shell ``` + ``` ``` @@ -89,17 +91,14 @@ To verify the creation of , you can also inspect information about it ### Sub-step 1 - ### Sub-step 2 - ## Conclusion [//]: # "Summarize everything that the reader will have learned and accomplished by the end of this tutorial." [//]: # "It should fulfill the promise made by the introductory paragraph at the top of the document." [//]: # "You may wish to link to another tutorial as the next logical step, but that could also be part of the 'See also' section." - ## Next steps [//]: # "Link to related documents, such as concepts, reference material or specific use cases." diff --git a/content/amplify/overview/overview-main-components.md b/content/amplify/overview/overview-main-components.md index ecb453b6e..35b736054 100644 --- a/content/amplify/overview/overview-main-components.md +++ b/content/amplify/overview/overview-main-components.md @@ -8,7 +8,7 @@ nd-docs: DOCS-976 ## What Is F5 NGINX Amplify? -[NGINX Amplify](https://amplify.nginx.com/signup/) offers in-depth monitoring for NGINX-based web applications. It simplifies the process of analyzing and resolving issues related to performance and scalability. +[NGINX Amplify](https://amplify.nginx.com/) offers in-depth monitoring for NGINX-based web applications. It simplifies the process of analyzing and resolving issues related to performance and scalability. With NGINX Amplify, you can: diff --git a/content/includes/waf/install-update-configuration.md b/content/includes/waf/install-update-configuration.md index d3fa18fe4..89aed3f0a 100644 --- a/content/includes/waf/install-update-configuration.md +++ b/content/includes/waf/install-update-configuration.md @@ -117,4 +117,9 @@ server { {{% /tab %}} -{{< /tabs >}} \ No newline at end of file +{{< /tabs >}} + +Once you have updated your configuration files, you can reload NGINX to apply the changes. You have two options depending on your environment: + +- `nginx -s reload` +- `sudo systemctl reload nginx` \ No newline at end of file diff --git a/content/waf/install/docker.md b/content/waf/install/docker.md index 530c8f326..a1d032b9a 100644 --- a/content/waf/install/docker.md +++ b/content/waf/install/docker.md @@ -67,7 +67,7 @@ You should now move to the section based on your configuration type: {{% tab name="nginx.conf" %}} -```nginx +```nginx {hl_lines=[4, 26, 27, 28]} user nginx; worker_processes auto; @@ -313,15 +313,39 @@ If you are not using using `custom_log_format.json` or the IP intelligence featu ### Update configuration files -{{< include "waf/install-update-configuration.md" >}} +Once you have installed F5 WAF for NGINX, you must load it as a module in the main context of your NGINX configuration. -{{}} +```nginx +load_module modules/ngx_http_app_protect_module.so; +``` -{{% tab name="nginx.conf" %}} +The Enforcer address must be added at the _http_ context: -`/etc/nginx/nginx.conf` +```nginx +app_protect_enforcer_address 127.0.0.1:50000; +``` + +And finally, F5 WAF for NGINX can enabled on a _http_, _server_ or _location_ context: ```nginx +app_protect_enable on; +``` + +{{< call-out "warning" >}} + +You should only enable F5 WAF for NGINX on _proxy_pass_ and _grpc_pass_ locations. + +{{< /call-out >}} + +Here are two examples of how these additions could look in configuration: some of them may already exist from when you created the files. + +{{< tabs name="example-configuration-files-multi" >}} + +{{% tab name="nginx.conf" %}} + +The default path for this file is `/etc/nginx/nginx.conf`. + +```nginx {hl_lines=[5, 33]} user nginx; worker_processes auto; @@ -331,6 +355,7 @@ load_module modules/ngx_http_app_protect_module.so; error_log /var/log/nginx/error.log notice; pid /var/run/nginx.pid; + events { worker_connections 1024; } @@ -359,18 +384,18 @@ http { } ``` - {{% /tab %}} {{% tab name="default.conf" %}} -`/etc/nginx/conf.d/default.conf` +The default path for this file is `/etc/nginx/conf.d/default.conf`. -```nginx +```nginx {hl_lines=[10]} server { listen 80; server_name domain.com; + location / { # F5 WAF for NGINX @@ -378,7 +403,7 @@ server { client_max_body_size 0; default_type text/html; - proxy_pass http://127.0.0.1:8080; + proxy_pass http://127.0.0.1:8080/; } } @@ -386,6 +411,7 @@ server { listen 8080; server_name localhost; + location / { root /usr/share/nginx/html; index index.html index.htm; @@ -483,7 +509,7 @@ sudo apk add openssl ca-certificates app-protect-module-plus Create a file for the F5 WAF for NGINX repository: -**/etc/yum.repos.d/app-protect-x-oss.repo** +`/etc/yum.repos.d/app-protect-x-oss.repo` ```shell [app-protect-x-oss] @@ -507,7 +533,7 @@ sudo dnf install app-protect-module-oss Create a file for the F5 WAF for NGINX repository: -**/etc/yum.repos.d/app-protect-x-plus.repo** +`/etc/yum.repos.d/app-protect-x-plus.repo` ```shell [app-protect-x-plus] @@ -587,7 +613,7 @@ The steps are identical for these platforms due to their similar architecture. Create a file for the F5 WAF for NGINX repository: -**/etc/yum.repos.d/app-protect-x-oss.repo** +`/etc/yum.repos.d/app-protect-x-oss.repo` ```shell [app-protect-x-oss] @@ -611,7 +637,7 @@ sudo yum install app-protect-module-oss Create a file for the F5 WAF for NGINX repository: -**/etc/yum.repos.d/app-protect-x-plus.repo** +`/etc/yum.repos.d/app-protect-x-plus.repo` ```shell [app-protect-x-plus] @@ -685,7 +711,7 @@ sudo apt-get install app-protect-module-plus Create a file for the F5 WAF for NGINX repository: -**/etc/yum.repos.d/app-protect-x-oss.repo** +`/etc/yum.repos.d/app-protect-x-oss.repo` ```shell [app-protect-x-oss] @@ -709,7 +735,7 @@ sudo yum install app-protect-module-oss Create a file for the F5 WAF for NGINX repository: -**/etc/yum.repos.d/app-protect-x-plus.repo** +`/etc/yum.repos.d/app-protect-x-plus.repo` ```shell [app-protect-x-plus] @@ -755,7 +781,7 @@ F5 WAF for NGINX should now be operational, and you can move onto [Post-installa {{% tab name="nginx.conf" %}} -```nginx +```nginx {hl_lines=[4, 26, 27, 28]} user nginx; worker_processes auto; @@ -1215,100 +1241,6 @@ CMD ["sh", "/root/entrypoint.sh"] {{< include "waf/install-update-configuration.md" >}} -{{}} - -{{% tab name="nginx.conf" %}} - -`/etc/nginx/nginx.conf` - -```nginx -user nginx; -worker_processes auto; - -# F5 WAF for NGINX -load_module modules/ngx_http_app_protect_module.so; - -error_log /var/log/nginx/error.log notice; -pid /var/run/nginx.pid; - -events { - worker_connections 1024; -} - -http { - include /etc/nginx/mime.types; - default_type application/octet-stream; - - log_format main '$remote_addr - $remote_user [$time_local] "$request" ' - '$status $body_bytes_sent "$http_referer" ' - '"$http_user_agent" "$http_x_forwarded_for"'; - - access_log /var/log/nginx/access.log main; - - sendfile on; - #tcp_nopush on; - - keepalive_timeout 65; - - #gzip on; - - # F5 WAF for NGINX - app_protect_enforcer_address 127.0.0.1:50000; - - include /etc/nginx/conf.d/*.conf; -} -``` - - -{{% /tab %}} - -{{% tab name="default.conf" %}} - -`/etc/nginx/conf.d/default.conf` - -```nginx -server { - listen 80; - server_name domain.com; - - location / { - - # F5 WAF for NGINX - app_protect_enable on; - - client_max_body_size 0; - default_type text/html; - proxy_pass http://127.0.0.1:8080/; - } -} - -server { - listen 8080; - server_name localhost; - - location / { - root /usr/share/nginx/html; - index index.html index.htm; - } - - # redirect server error pages to the static page /50x.html - # - error_page 500 502 503 504 /50x.html; - location = /50x.html { - root /usr/share/nginx/html; - } -} -``` - -{{% /tab %}} - -{{< /tabs >}} - -Once you have updated your configuration files, you can reload NGINX to apply the changes. You have two options depending on your environment: - -- `nginx -s reload` -- `sudo systemctl reload nginx` - F5 WAF for NGINX should now be operational, and you can move onto [Post-installation checks](#post-installation-checks). ## Post-installation checks diff --git a/content/waf/install/virtual-environment.md b/content/waf/install/virtual-environment.md index 14252a7bd..896a04f61 100644 --- a/content/waf/install/virtual-environment.md +++ b/content/waf/install/virtual-environment.md @@ -202,113 +202,7 @@ sudo apt-get install app-protect ## Update configuration files -Once you have installed F5 WAF for NGINX, you must load it as a module in the main context of your NGINX configuration. - -```nginx -load_module modules/ngx_http_app_protect_module.so; -``` - -And finally, F5 WAF for NGINX can enabled on a _http_, _server_ or _location_ context: - -```nginx -app_protect_enable on; -``` - -{{< call-out "warning" >}} - -You should only enable F5 WAF for NGINX on _proxy_pass_ and _grpc_pass_ locations. - -{{< /call-out >}} - -Here are two examples of how these additions could look in configuration files: - -{{< tabs name="configuration-examples" >}} - -{{% tab name="nginx.conf" %}} - -The default path for this file is `/etc/nginx/nginx.conf`. - -```nginx {hl_lines=[5]} -user nginx; -worker_processes auto; - -# F5 WAF for NGINX -load_module modules/ngx_http_app_protect_module.so; - -error_log /var/log/nginx/error.log notice; -pid /var/run/nginx.pid; - - -events { - worker_connections 1024; -} - -http { - include /etc/nginx/mime.types; - default_type application/octet-stream; - - log_format main '$remote_addr - $remote_user [$time_local] "$request" ' - '$status $body_bytes_sent "$http_referer" ' - '"$http_user_agent" "$http_x_forwarded_for"'; - - access_log /var/log/nginx/access.log main; - - sendfile on; - #tcp_nopush on; - - keepalive_timeout 65; - - #gzip on; - - include /etc/nginx/conf.d/*.conf; -} -``` - -{{% /tab %}} - -{{% tab name="default.conf" %}} - -The default path for this file is `/etc/nginx/conf.d/default.conf`. - -```nginx {hl_lines=[9]} -server { - listen 80; - server_name domain.com; - - - location / { - - # F5 WAF for NGINX - app_protect_enable on; - - client_max_body_size 0; - default_type text/html; - proxy_pass http://127.0.0.1:8080/; - } -} - -server { - listen 8080; - server_name localhost; - - - location / { - root /usr/share/nginx/html; - index index.html index.htm; - } - - # redirect server error pages to the static page /50x.html - # - error_page 500 502 503 504 /50x.html; - location = /50x.html { - root /usr/share/nginx/html; - } -} -``` - -{{% /tab %}} - -{{< /tabs >}} +{{< include "waf/install-update-configuration.md" >}} ## Post-installation checks diff --git a/documentation/linting-tools.md b/documentation/linting-tools.md new file mode 100644 index 000000000..7313307b8 --- /dev/null +++ b/documentation/linting-tools.md @@ -0,0 +1,43 @@ +# Linting tools + +This document describes the linting tools used for NGINX documentation and how to use them. + +They can be executed automatically with [pre-commit](/documentation/pre-commit.md). + +## Git + +Git commit messages are linted with pre-commit using [gitlint](https://github.com/jorisroovers/gitlint). + +The configuration file, `.gitlint`, is located at the root of the repository. + +It checks the length of your message lines, that the body is not empty, and that the title adheres to [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary). + +For guidance on preferred detail, read the [Commit messages](/documentation/git-conventions.md#commit-messages) information. + +## Markdown + +Markdown files are linted using [markdownlint](https://github.com/DavidAnson/markdownlint). + +The configuration file, `.markdownlint.yml`, is located at the root of the repository. + +We use comments in the configuration file so maintainers can understand the rules at a glance. + +To interact with the markdownlint library, we use the command line interface (CLI) tool `markdownlint-cli2`. + +It is installed using `npm`: + +```shell +npm install markdownlint-cli2 --global +``` + +To install npm (With node.js), you can use a tool such as [fnm](https://github.com/Schniz/fnm) or [nvm](https://github.com/nvm-sh/nvm). + +Once `markdownlint-cli2` has been installed, you can use it by passing Markdown files to the command as arguments. + +```text +➜ markdownlint-cli2 README.md +markdownlint-cli2 v0.18.1 (markdownlint v0.38.0) +Finding: README.md +Linting: 1 file(s) +Summary: 0 error(s) +``` \ No newline at end of file diff --git a/documentation/pre-commit.md b/documentation/pre-commit.md index af490a726..2029d1bdb 100644 --- a/documentation/pre-commit.md +++ b/documentation/pre-commit.md @@ -2,7 +2,11 @@ [pre-commit](https://pre-commit.com/) is a command-line tool used for automatic linting. -It is currently *optional*, and used for consistent [Git conventions](/documentation/git-conventions.md), but will be used for more in the future. +It is currently *optional*, and used for consistent [Git conventions](/documentation/git-conventions.md), and [linting tools](/documentation/linting-tools.md). + +To use pre-commit, you *must* have all of the linting tool requirements, as every integration will be executed by pre-commit. + +Otherwise, you will need to manually edit the configuration file to disable integrations whose requirements you do not have installed. The configuration file is located at the root of the repository, [pre-commit-config.yaml](/.pre-commit-config.yaml). @@ -24,10 +28,30 @@ pre-commit install It will then run every time you use `git commit`. -If you encounter an error about a missing configuration file, you are likely working in a branch that has not synced changes from `main`. +Periodically, you should update the pre-commit libraries using `autoupdate`: + +```shell +pre-commit autoupdate +``` + +## Use pre-commit + +pre-commit will automatically trigger when using git based on the specific integration and how it has been configured. -You will need to sync changes from `main` or temporarily uninstall pre-commit to address the error. +You can trigger all of the integrations on modified files by running pre-commit without any arguments: ```shell -pre-commit uninstall +pre-commit ``` + +You can trigger an individual integration using its id (Found in the configuration file): + +```shell +pre-commit run markdownlint-cli2 +``` + +You can trigger an integration on specific files by passing them as parameters to the `--files` argument: + +```shell +pre-commit run markdownlint-cli2 --files README.md +``` \ No newline at end of file From f1dd8878c3bc0c768635c12805177f38fefa3bb7 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 22 Oct 2025 14:58:58 +0100 Subject: [PATCH 2/3] feat: Add core limitations and missing Docker configuration This commit adds the following changes for F5 WAF for NGINX: - A new section of Technical Specifications with CPU core limits - Updates to the multi-container Docker deployment - Configuration updates for the repository's automatic labeller Additionally, a small heading naming issue was fixed in the changelog, as well as a formatting style based on our Markdown linting rules. --- .github/labeler.yml | 31 +++++----- content/waf/changelog/2024.md | 12 ++-- content/waf/changelog/_index.md | 26 +++++++-- .../fundamentals/technical-specifications.md | 7 ++- content/waf/install/docker.md | 56 ++++++++++++++++++- 5 files changed, 103 insertions(+), 29 deletions(-) diff --git a/.github/labeler.yml b/.github/labeler.yml index c8cd64f8b..d3684b539 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -23,6 +23,12 @@ product/amplify: - changed-files: - any-glob-to-any-file: 'content/amplify/**' +product/dos: + - changed-files: + - any-glob-to-any-file: + - 'content/nap-dos/**' + - 'content/includes/nap-dos/**' + product/controller: - changed-files: - any-glob-to-any-file: @@ -37,18 +43,6 @@ product/modsec-waf: - changed-files: - any-glob-to-any-file: 'content/modsec-waf/**' -product/nap-dos: - - changed-files: - - any-glob-to-any-file: - - 'content/nap-dos/**' - - 'content/includes/nap-dos/**' - -product/nap-waf: - - changed-files: - - any-glob-to-any-file: - - 'content/nap-waf/**' - - 'content/includes/nap-waf/**' - product/ngf: - changed-files: - any-glob-to-any-file: @@ -97,12 +91,19 @@ product/unit: - 'content/unit/**' - 'content/includes/unit/**' +product/waf: + - changed-files: + - any-glob-to-any-file: + - 'content/waf/**' + - 'content/includes/waf/**' + # Other labels process documentation: - changed-files: - any-glob-to-any-file: - 'templates/**' + - 'documentation/**' - '*.md' - 'LICENSE' @@ -122,6 +123,8 @@ tooling: - '*.sh' - '*.js' - 'Makefile' - - '.vale.ini' - - '.gitignore' - '.gitattributes' + - '.gitignore' + - '.gitlint' + - '.markdownlint.yaml' + - '.vale.ini' diff --git a/content/waf/changelog/2024.md b/content/waf/changelog/2024.md index 184c50578..a4e2c4578 100644 --- a/content/waf/changelog/2024.md +++ b/content/waf/changelog/2024.md @@ -17,7 +17,7 @@ For the current year, view [the top-level changelog]({{< ref "/waf/changelog/">} ## F5 WAF for NGINX 5.4 / 4.12 -_November 19th, 2024_ +Released _November 19th, 2024_ ### New features @@ -76,7 +76,7 @@ sudo service nginx restart ## F5 WAF for NGINX 5.3 / 4.11 -_September 25, 2024_ +Released _September 25, 2024_. ### New features @@ -116,7 +116,7 @@ _September 25, 2024_ ## F5 WAF for NGINX 5.2 / 4.10 -_May 29, 2024_ +Released _May 29, 2024_. ### New features @@ -149,7 +149,7 @@ _May 29, 2024_ ## F5 WAF for NGINX 5.1 / 4.9 -_April 18, 2024_ +Released _April 18, 2024_. ### New features @@ -188,7 +188,7 @@ _April 18, 2024_ ## F5 WAF for NGINX 5.0 / 4.8.1 -_March 19, 2024_ +Released _March 19, 2024_. ### New features @@ -199,7 +199,7 @@ _March 19, 2024_ {{< table >}} -| Distribution name | NGINX Open Source (5.1) | NGINX Plus (5.1) | NGINX Plus (4.8.1) | +| Distribution name | NGINX Open Source (5.0) | NGINX Plus (5.0) | NGINX Plus (4.8.1) | | ------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------- |----------------------------------------------------| | Alpine 3.17 | _app-protect-module-oss-1.25.4+4.815.0-r1.apk_ | _app-protect-module-plus-31+4.815.0-r1.apk_ | _app-protect-31.4.815.0-r1.apk_ | | Amazon Linux 2023 | _app-protect-module-oss-1.25.4+4.815.0-1.amzn2023.ngx.x86_64.rpm_ | _app-protect-module-plus-31+4.815.0-1.amzn2023.ngx.x86_64.rpm_ | _app-protect-31+4.815.0-1.amzn2023.ngx.x86_64.rpm_ | diff --git a/content/waf/changelog/_index.md b/content/waf/changelog/_index.md index 32d6ba815..c169cf58b 100644 --- a/content/waf/changelog/_index.md +++ b/content/waf/changelog/_index.md @@ -19,7 +19,7 @@ For older releases, check the changelogs for previous years: [2024]({{< ref "/wa ## F5 WAF for NGINX 5.9 -_September 29th, 2025_ +Released _September 29th, 2025_. ### New features @@ -32,6 +32,21 @@ _September 29th, 2025_ - Package and container artifacts now share the same version numbers - Upgrade processes remain the same as earlier releases - No breaking changes + +{{< call-out "important" >}} + +"_V4_" is now represented in the following pages or sections: + +- [Virtual machine or bare metal]({{< ref "/waf/install/virtual-environment.md">}}) +- Docker [Hybrid]({{< ref "/waf/install/docker.md#hybrid-configuration" >}}) and [Single container]({{< ref "/waf/install/docker.md#single-container-configuration" >}}) configuration + +"_V5_" is now represented in the following pages or sections: + +- [Kubernetes]({{< ref "/waf/install/kubernetes.md">}}) +- Docker [Multi-container]({{< ref "/waf/install/docker.md#multi-container-configuration" >}}) configuration + +{{< /call-out >}} + - Restructured documentation - Product name change - Version alignment @@ -58,7 +73,7 @@ _September 29th, 2025_ ## NGINX App Protect WAF 5.8 / 4.16 -_August 13th, 2025_ +Released _August 13th, 2025_. ### New features @@ -84,7 +99,7 @@ _August 13th, 2025_ ## NGINX App Protect WAF 5.7 / 4.15 -_June 24th, 2025_ +Released _June 24th, 2025_. ### New features @@ -124,10 +139,9 @@ _June 24th, 2025_ {{< /table >}} - ## NGINX App Protect WAF 5.6 / 4.14 -_April 1st, 2025_ +Released _April 1st, 2025_. ### New features @@ -167,7 +181,7 @@ _April 1st, 2025_ ## NGINX App Protect WAF 5.5 / 4.13 -_January 30th, 2025_ +Released _January 30th, 2025_. ### New features diff --git a/content/waf/fundamentals/technical-specifications.md b/content/waf/fundamentals/technical-specifications.md index 514eafddf..cfe7bfddd 100644 --- a/content/waf/fundamentals/technical-specifications.md +++ b/content/waf/fundamentals/technical-specifications.md @@ -14,6 +14,10 @@ nd-product: NAP-WAF This page outlines the technical specifications for F5 WAF for NGINX, which includes the minimum requirements and supported platforms. +## Resource limitations + +- F5 WAF for NGINX supports a **maximum** of **127** CPU cores. + ## Supported deployment environments You can deploy F5 WAF for NGINX in the following environments: @@ -54,9 +58,8 @@ The F5 WAF for NGINX package has the following dependencies: | app-protect-threat-campaigns | The F5 WAF for NGINX threat campaigns update package | | nginx-plus-module-appprotect | NGINX Plus dynamic module for F5 WAF for NGINX | - 1. _Optional dependencies_ -2. _This module needs to be installed separately, and includes a client for downloading and updating the feature's database_ +1. _This module needs to be installed separately, and includes a client for downloading and updating the feature's database_ ## Supported security policy features diff --git a/content/waf/install/docker.md b/content/waf/install/docker.md index a1d032b9a..d54ca7d2d 100644 --- a/content/waf/install/docker.md +++ b/content/waf/install/docker.md @@ -445,7 +445,61 @@ Once you have updated your configuration files, you can reload NGINX to apply th #### Create and run a Docker Compose file -{{< include "waf/install-services-compose.md" >}} +Create a _docker-compose.yml_ file with the following contents in your host environment, replacing image tags as appropriate: + +```yaml +services: + nginx: + container_name: nginx + image: nginx-app-protect-5 + volumes: + - app_protect_bd_config:/opt/app_protect/bd_config + - app_protect_config:/opt/app_protect/config + - app_protect_etc_config:/etc/app_protect/conf + - /conf/nginx.conf:/etc/nginx/nginx.conf + - /conf/default.conf:/etc/nginx/conf.d/default.conf + - ./license.jwt:/etc/nginx/license.jwt # Only necessary when using NGINX Plus + networks: + - waf_network + ports: + - "80:80" + + waf-enforcer: + container_name: waf-enforcer + image: waf-enforcer:5.2.0 + environment: + - ENFORCER_PORT=50000 + ports: + - "50000:50000" + volumes: + - /opt/app_protect/bd_config:/opt/app_protect/bd_config + networks: + - waf_network + restart: always + + waf-config-mgr: + container_name: waf-config-mgr + image: waf-config-mgr:5.2.0 + volumes: + - /opt/app_protect/bd_config:/opt/app_protect/bd_config + - /opt/app_protect/config:/opt/app_protect/config + - /etc/app_protect/conf:/etc/app_protect/conf + restart: always + network_mode: none + depends_on: + waf-enforcer: + condition: service_started + +networks: + waf_network: + driver: bridge +``` + +To start the F5 WAF for NGINX services, use `docker compose up` in the same folder as the _docker-compose.yml_ file: + +```shell +sudo docker compose up -d +``` You can now review the operational status of F5 WAF for NGINX using the [Post-installation checks]({{< ref "/waf/install/docker.md#post-installation-checks" >}}). From 8f5a4079b28d575b29cf042638a0c9dc20d6b811 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 22 Oct 2025 15:13:26 +0100 Subject: [PATCH 3/3] Update content/waf/changelog/2024.md --- content/waf/changelog/2024.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/waf/changelog/2024.md b/content/waf/changelog/2024.md index a4e2c4578..4296f32e5 100644 --- a/content/waf/changelog/2024.md +++ b/content/waf/changelog/2024.md @@ -17,7 +17,7 @@ For the current year, view [the top-level changelog]({{< ref "/waf/changelog/">} ## F5 WAF for NGINX 5.4 / 4.12 -Released _November 19th, 2024_ +Released _November 19th, 2024_. ### New features