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