feat: Update NIC Docker docs, related files

Author: ADubhlaoich

content/includes/licensing-and-reporting/download-certificates-from-myf5.md

@@ -0,0 +1,9 @@
+---
+files:
+- content/includes/use-cases/credential-download-instructions.md
+---
+
+1. Log in to [MyF5](https://my.f5.com/manage/s/).
+1. Go to **My Products and Plans** > **Subscriptions**.
+1. Select the product subscription.
+1. Download the **SSL Certificate** and **Private Key** files.

content/includes/licensing-and-reporting/download-jwt-from-myf5.md

@@ -1,8 +1,19 @@
 ---
 docs:
+files:
+- content/includes/nim/docker/docker-registry-login.md
+- content/includes/use-cases/credential-download-instructions.md
+- content/nap-waf/v5/admin-guide/install.md
+- content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md
+- content/nginx-one/connect-instances/connect-nginx-plus-container-images-to-nginx-one.md
+- content/nim/admin-guide/add-license.md
+- content/nim/deploy/docker/deploy-nginx-plus-and-agent-docker.md
+- content/nim/disconnected/add-license-disconnected-deployment.md
+- content/solutions/about-subscription-licenses.md
+- content/solutions/r33-pre-release-guidance-for-automatic-upgrades.md
 ---
 
 1. Log in to [MyF5](https://my.f5.com/manage/s/).
 2. Go to **My Products & Plans > Subscriptions** to see your active subscriptions.
-3. Find your NGINX products or services subscription, and select the **Subscription ID** for details.
+3. Find your NGINX subscription, and select the **Subscription ID** for details.
 4. Download the **JSON Web Token** from the subscription page.

content/includes/use-cases/credential-download-instructions.md

@@ -0,0 +1,19 @@
+In order to obtain a container image, you will need the JSON Web Token file or SSL certificate and private key files provided with your NGINX Plus subscription. 
+
+These files grant access to the package repository from which the script will download the NGINX Plus package:
+
+{{< tabs name="product_keys" >}}
+
+{{< tab name="JSON Web Token" >}}
+
+{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}}
+
+{{< /tab >}}
+
+{{< tab name="SSL" >}}
+
+{{< include "licensing-and-reporting/download-certificates-from-myf5.md" >}}
+
+{{< /tab >}}
+
+{{< /tabs >}}

content/includes/use-cases/docker-registry-instructions.md

@@ -0,0 +1,49 @@
+---
+files:
+- content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md
+- content/nic/installation/nic-images/registry-download.md
+---
+
+This step describes how to use Docker to communicate with the F5 Container Registry located at `private-registry.nginx.com`.
+
+{{< call-out "note" >}}
+
+The steps provided are for Linux. For Mac or Windows, see the [Docker for Mac](https://docs.docker.com/docker-for-mac/#add-client-certificates) or [Docker for Windows](https://docs.docker.com/docker-for-windows/#how-do-i-add-client-certificates) documentation. 
+
+For more details on Docker Engine security, you can refer to the [Docker Engine Security documentation](https://docs.docker.com/engine/security/).
+
+{{< /call-out >}}
+
+{{<tabs name="docker_login">}}
+
+{{%tab name="JSON Web Token"%}}
+
+Open the JSON Web Token file previously downloaded from [MyF5](https://my.f5.com) customer portal (for example, `nginx-repo-12345abc.jwt`) and copy its contents.
+
+Log in to the Docker registry using the contents of the JSON Web Token file:
+
+```shell
+docker login private-registry.nginx.com --username=<output_of_jwt_token> --password=none
+```
+
+{{% /tab %}}
+
+{{%tab name="SSL"%}}
+
+Create a directory and copy your certificate and key to this directory:
+
+```shell
+mkdir -p /etc/docker/certs.d/private-registry.nginx.com
+cp <path-to-your-nginx-repo.crt> /etc/docker/certs.d/private-registry.nginx.com/client.cert
+cp <path-to-your-nginx-repo.key> /etc/docker/certs.d/private-registry.nginx.com/client.key
+```
+
+Log in to the Docker registry:
+
+```shell
+docker login private-registry.nginx.com
+```
+
+{{% /tab %}}
+
+{{% /tabs %}}

content/nginx/admin-guide/installing-nginx/installing-nginx-docker.md

@@ -88,61 +88,13 @@ where:
 
 - the `jq` command is used to format the JSON output for easier reading and requires the [jq](https://jqlang.github.io/jq/) JSON processor to be installed.
 
+### Download your subscription credential files
 
+{{< include "use-cases/credential-download-instructions.md" >}}
 
-### Download the JSON Web Token or NGINX Plus certificate and key {#myf5-download}
+### Set up Docker for the F5 Container Registry
 
-Before you get a container image, you should provide the JSON Web Token file or SSL certificate and private key files provided with your NGINX Plus subscription. These files grant access to the package repository from which the script will download the NGINX Plus package:
-
-{{<tabs name="product_keys">}}
-
-{{%tab name="JSON Web Token"%}}
-{{< include "licensing-and-reporting/download-jwt-from-myf5.md" >}}
-{{% /tab %}}
-
-{{%tab name="SSL"%}}
-1. Log in to the [MyF5](https://my.f5.com) customer portal.
-2. Go to **My Products and Plans** > **Subscriptions**.
-3. Select the product subscription.
-4. Download the **SSL Certificate** and **Private Key** files.
-{{% /tab %}}
-
-{{% /tabs %}}
-
-### Set up Docker for NGINX Plus container registry
-
-Set up Docker to communicate with the NGINX Container Registry located at `private-registry.nginx.com`.
-
-{{<tabs name="docker_login">}}
-
-{{%tab name="JSON Web Token"%}}
-Open the JSON Web Token file previously downloaded from [MyF5](https://my.f5.com) customer portal (for example, `nginx-repo-12345abc.jwt`) and copy its contents.
-
-Log in to the docker registry using the contents of the JSON Web Token file:
-
-```shell
-docker login private-registry.nginx.com --username=<output_of_jwt_token> --password=none
-```
-{{% /tab %}}
-
-{{%tab name="SSL"%}}
-Create a directory and copy your certificate and key to this directory:
-
-```shell
-mkdir -p /etc/docker/certs.d/private-registry.nginx.com
-cp <path-to-your-nginx-repo.crt> /etc/docker/certs.d/private-registry.nginx.com/client.cert
-cp <path-to-your-nginx-repo.key> /etc/docker/certs.d/private-registry.nginx.com/client.key
-```
-The steps provided are for Linux. For Mac or Windows, see the [Docker for Mac](https://docs.docker.com/docker-for-mac/#add-client-certificates) or [Docker for Windows](https://docs.docker.com/docker-for-windows/#how-do-i-add-client-certificates) documentation. For more details on Docker Engine security, you can refer to the [Docker Engine Security documentation](https://docs.docker.com/engine/security/).
-
-Log in to the docker registry:
-
-```shell
-docker login private-registry.nginx.com
-```
-{{% /tab %}}
-
-{{% /tabs %}}
+{{< include "use-cases/docker-registry-instructions.md" >}}
 
 ### Pull the image
 
@@ -192,7 +144,6 @@ For NGINX modules, run:<!-- Is this enough info?-->
 docker pull private-registry.nginx.com/nginx-plus/modules:<version-tag>
 ```
 
-
 {{< include "security/jwt-password-note.md" >}}
 
 ### Push the image to your private registry

content/nic/installation/nic-images/add-image-to-cluster.md

@@ -36,9 +36,9 @@ helm install my-release -n nginx-ingress oci://ghcr.io/nginx/charts/nginx-ingres
 You can also use the certificate and key from the MyF5 portal and the Docker registry API to list the available image tags for the repositories, for example:
 
 ```shell
-curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq
+curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
 ```
-```text
+```json
 {
 "name": "nginx-ic/nginx-plus-ingress",
 "tags": [
@@ -51,9 +51,9 @@ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list
 ```
 
 ```shell
-curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq
+curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
 ```
-```text
+```json
 {
 "name": "nginx-ic-nap/nginx-plus-ingress",
 "tags": [
@@ -65,9 +65,9 @@ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/
 ```
 
 ```shell
-$ curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq
+curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
 ```
-```text
+```json
 {
 "name": "nginx-ic-dos/nginx-plus-ingress",
 "tags": [
@@ -77,6 +77,8 @@ $ curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tag
 }
 ```
 
+The `jq` command was used in these examples to make the JSON output easier to read.
+
 ### Add the image from source
 
 The [Installation with Helm]({{< ref "/nic/installation/installing-nic/installation-with-helm.md#install-the-helm-chart-from-source" >}}) documentation has a section describing how to use sources: these are the unique steps for Docker secrets using JWT tokens.

content/nic/installation/nic-images/registry-download.md

@@ -15,7 +15,6 @@ The F5 Registry images include versions with NGINX App Protect WAF and NGINX App
 
 To follow these steps, you will need the following pre-requisites:
 
-- [Create a license Secret]({{< ref "/nic/installation/create-license-secret.md" >}})
 - [Docker v18.09 or higher](https://docs.docker.com/engine/release-notes/18.09/)
 
 You can also get the NGINX Ingress Controller image using the following alternate methods:
@@ -24,17 +23,13 @@ You can also get the NGINX Ingress Controller image using the following alternat
 - [Build NGINX Ingress Controller]({{< ref "/nic/installation/build-nginx-ingress-controller.md" >}}) 
 - For NGINX Open Source, you can pull [an image from DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/)
 
-## Set up Docker for F5 Container Registry
+### Download your subscription credential files
 
-Start by setting up Docker to communicate with the F5 Container Registry located at `private-registry.nginx.com`. If you're using Linux, follow these steps to create a directory and add your certificate and key:
+{{< include "use-cases/credential-download-instructions.md" >}}
 
-```shell
-mkdir -p /etc/docker/certs.d/private-registry.nginx.com
-cp <path-to-your-nginx-repo.crt> /etc/docker/certs.d/private-registry.nginx.com/client.cert
-cp <path-to-your-nginx-repo.key> /etc/docker/certs.d/private-registry.nginx.com/client.key
-```
+### Set up Docker for the F5 Container Registry
 
-The steps provided are for Linux. For Mac or Windows, consult the [Docker for Mac](https://docs.docker.com/docker-for-mac/#add-client-certificates) or [Docker for Windows](https://docs.docker.com/docker-for-windows/#how-do-i-add-client-certificates) documentation. For more details on Docker Engine security, you can refer to the [Docker Engine Security documentation](https://docs.docker.com/engine/security/).
+{{< include "use-cases/docker-registry-instructions.md" >}}
 
 ## Pull the image
 
@@ -70,7 +65,6 @@ Replace `<version-tag>` with the specific version you need, for example, `{{< ni
    docker pull private-registry.nginx.com/nap/waf-enforcer:<waf-version-tag>
    ```
 
-
 - For NGINX Plus Ingress Controller with NGINX App Protect DoS, run:
 
    ```shell
@@ -83,10 +77,14 @@ Replace `<version-tag>` with the specific version you need, for example, `{{< ni
    docker pull private-registry.nginx.com/nginx-ic-nap-dos/nginx-plus-ingress:<version-tag>
    ```
 
-You can use the Docker registry API to list the available image tags by running the following commands. Replace `<path-to-client.key>` with the location of your client key and `<path-to-client.cert>` with the location of your client certificate. The `jq` command is used to format the JSON output for easier reading.
+You can use the Docker registry API to list the available image tags by running the following commands. Replace `<path-to-client.key>` with the location of your client key and `<path-to-client.cert>` with the location of your client certificate. 
+
+The `jq` command was used in these examples to make the JSON output easier to read.
 
+```shell
+curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
+```
 ```json
-$ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq
 {
   "name": "nginx-ic/nginx-plus-ingress",
   "tags": [
@@ -96,8 +94,12 @@ $ curl https://private-registry.nginx.com/v2/nginx-ic/nginx-plus-ingress/tags/li
     "{{< nic-version >}}"
   ]
 }
+```
 
-$ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq
+```shell
+curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
+```
+```json
 {
   "name": "nginx-ic-nap/nginx-plus-ingress",
   "tags": [
@@ -106,8 +108,12 @@ $ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tag
     "{{< nic-version >}}"
   ]
 }
+```
 
-$ curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert> | jq
+```shell
+curl https://private-registry.nginx.com/v2/nginx-ic-dos/nginx-plus-ingress/tags/list --key <path-to-client.key> --cert <path-to-client.cert>
+```
+```json
 {
   "name": "nginx-ic-dos/nginx-plus-ingress",
   "tags": [
@@ -169,7 +175,7 @@ After pulling the image, tag it and upload it to your private registry.
 
 ## Troubleshooting
 
-If you encounter issues while following this guide, here are solutions to common problems:
+If you encounter issues while following this guide, here are some possible solutions:
 
 - **Certificate errors**
   - **Likely Cause**: Incorrect certificate or key location, or using an NGINX Plus certificate.
@@ -181,7 +187,7 @@ If you encounter issues while following this guide, here are solutions to common
 
 - **Can't pull the image**
   - **Likely Cause**: Mismatched image name or tag.
-  - **Solution**: Double-check the image name and tag against the [Tech Specs guide]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}).
+  - **Solution**: Double-check the image name and tag matches the [Technical specifications]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}) document.
 
 - **Failed to push to private registry**
   - **Likely Cause**: Not logged into your private registry or incorrect image tagging.

documentation/README.md

@@ -19,4 +19,5 @@ If you're interested in contributing to the [NGINX documentation website](https:
 - [Managing content with Hugo](/documentation/writing-hugo.md)
 - [Proposals](/documentation/proposals/README.md)
 - [Set up pre-commit](/documentation/pre-commit.md)
+- [Using include files](/documentation/include-files.md)
 - [Writing style guide](/documentation/style-guide.md)

documentation/include-files.md

@@ -0,0 +1,43 @@
+# Using Include files
+
+_Include files_, often referred to as _includes_, are Markdown files with self-contained text fragments used by Hugo for content re-use.
+
+They enable contributors to maintain a single source of truth for information that is often repeated, such as how to download credential files.
+
+We use them to [avoid repeating ourselves](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself), and create consistency in similar instructional steps.
+
+Include files are designed to be context-agnostic and should not rely on or assume any prior content.
+
+The files are located in the [content/includes](https://github.com/nginxinc/docs/tree/main/content/includes) folder, and are implemented using the Hugo `include` shortcode:
+
+```text
+{{< include "use-cases/docker-registry-instructions.md" >}}
+```
+
+Putting the previous example in any Markdown file would embed the contents of `content/includes/use-cases/docker-registry-instructions.md` wherever the shortcode was used.
+
+For guidance on other Hugo shortcodes, read the [Managing content with Hugo](/documentation/writing-hugo.md) document.
+
+## Guidelines for include files
+
+To make sure includes are effective and easy to maintain, follow these guidelines:
+
+- **Only use includes for repeated content**: Create an include only if the content appears in at least **two locations**. Using an include for single-use content adds unnecessary complexity and makes maintenance harder.
+- **Keep includes small and modular**: Write narrowly scoped snippets to maximize flexibility and reuse.
+- **Avoid nesting includes**: If there’s another way to achieve the same outcome, avoid nesting includes. While possible, it complicates reviews and maintenance. A flat structure is simple.
+- **Don't include heading**: Do not include headings in include files. These headings won't appear in a document's table of contents and may break the linear flow of the surrounding content. Add headings directly to the document instead.
+- **Don't start documents with includes**: The opening of most document is the introduction which explains its purpose. Includes are reused text, so starting multiple documents with identical content could look odd, especially in search results.
+- **Do not add the F5 prefix to product names in includes**: The brand name is required only on [the first mention in a document](/documentation/style-guide.md#f5-brand-trademarks-and-product-names).
+
+## Include file index
+
+To aid in discoverability of include files, this index is maintained to offer contributors a reference for existing entries.
+
+When viewing an include file, you may also see the `files`: parameter in the frontmatter, which shows where the file is currently in use.
+
+| **_File name_** | **_Description_** |
+| ----------------| ------------------ |
+| [_licensing-and-reporting/download-jwt-from-myf5.md_](/content/includes/licensing-and-reporting/download-jwt-from-myf5.md) | Instructions for downloading a JSON Web Token from MyF5 |
+| [_licensing-and-reporting/download-certificates-from-myf5.md_](/content/includes/licensing-and-reporting/download-certificates-from-myf5.md) | Instructions for downloading certificate files from MyF5 |
+| [_use-cases/credential-download-instructions.md_](/content/includes/use-cases/credential-download-instructions.md) | Parallel tabbed instructions for downloading credential files from MyF5 |
+| [_use-cases/docker-registry-instructions.md_](/content/includes/use-cases/docker-registry-instructions.md) | Parallel tabbed instructions for listing Docker images from the F5 Registry |