From 657bbc08463cfbbc4dd211decf61ae9bc402ce32 Mon Sep 17 00:00:00 2001 From: Micheal Kingston <44472403+mkingst@users.noreply.github.com> Date: Wed, 12 Feb 2025 09:38:25 +0000 Subject: [PATCH 1/2] Delete content/nim/deploy/docker/deploy-nginx-instance-manager-docker.md --- .../deploy-nginx-instance-manager-docker.md | 309 ------------------ 1 file changed, 309 deletions(-) delete mode 100644 content/nim/deploy/docker/deploy-nginx-instance-manager-docker.md diff --git a/content/nim/deploy/docker/deploy-nginx-instance-manager-docker.md b/content/nim/deploy/docker/deploy-nginx-instance-manager-docker.md deleted file mode 100644 index f392449ec..000000000 --- a/content/nim/deploy/docker/deploy-nginx-instance-manager-docker.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -categories: -- -date: "2024-06-06T12:00:00-07:00" -description: -doctypes: -- deployment guide -tags: -- docs -title: "Deploy in a single container (demo only)" -toc: true -versions: [] -weight: 100 -docs: "DOCS-1652" ---- - -{{< call-out "important" "Single container deployment not suitable for production" "fa-solid fa-triangle-exclamation" >}} -This single container deployment is intended for demo purposes and small-scale deployments only. It is not recommended for production environments. -{{}} - -## Overview - -This guide will show you how to deploy and use F5 NGINX Instance Manager with Docker. The NGINX Instance Manager container is a single Docker image that includes all dependencies, making it easy to quickly set up NGINX Instance Manager with NGINX Open Source. - -This deployment is ideal for: - -- Product demos -- Instance counting -- Small-scale environments (20 instances or fewer) - -{{< call-out "important" "This Docker option only works for Instance Manager 2.17 and will no longer be supported" "fa-solid fa-triangle-exclamation" >}} -Please use the [Docker Compose]({{< relref "/nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md" >}}) option for Instance Manager 2.18 or later, as it includes better resiliency and fault tolerance. -{{< /call-out >}} - -By the end of this guide, you'll be able to: - -- Perform a quick test without persistent storage. -- Persist data to a volume. -- Set the admin password with an environment variable. -- Override self-signed API gateway certificates. -- Configure user access to the container using an `.htpasswd` file. - ---- - -## What you need - -- A working version of [Docker](https://docs.docker.com/get-docker/) -- Your NGINX Instance Manager subscription's JSON Web Token from [MyF5](https://my.f5.com/manage/s/subscriptions). You can use the same JSON Web Token as NGINX Plus in your MyF5 portal. - ---- - -## Before you start - -{{< include "/nim/decoupling/note-legacy-nms-references.md" >}} - -### Set up Docker for NGINX container registry - -To set up Docker to communicate with the NGINX container registry located at `private-registry.nginx.com`, follow these steps: - -{{< include "/nim/docker/docker-registry-login.md" >}} - -### Data persistence - -- A single volume mount is required to persist the NGINX Instance Manager databases. For example: `--volume=/myvolume/nim:/data` -- An optional volume can be used to add a custom `.htpasswd` file for admin and user authentication. For example: `--volume=/myvolume/pass/.htpasswd:/.htpasswd` - -### Supported environment variables - -- `NMS_PERSIST_DISABLE`: Do not persist data to a volume. All data will be lost after the container stops or restarts. -- `NMS_ADMIN_PASSWORD`: Set an admin password. -- `NMS_APIGW_CERT`: Override the API gateway self-signed certificate. -- `NMS_APIGW_KEY`: Override the API gateway self-signed key. -- `NMS_APIGW_CA`: Override the API gateway self-signed CA. -- `LOG_LEVEL`: Set the logging level for NGINX Instance Manager. - ---- - -## Build examples - -### Quick test without persistent storage - -1. Run the following Docker command, replacing the placeholders with the appropriate values: - - ``: desired hostname - - ``: password for the admin account - - ``: specific release version you want to use (**note:** `latest` is not supported) - - ```bash - docker run -it --rm \ - --hostname= \ - -e NMS_PERSIST_DISABLE \ - -e NMS_ADMIN_PASSWORD="" \ - -p 8443:443 \ - private-registry.nginx.com/nms/nim-bundle: - ``` - -
- - {{< call-out "tip" "Example:" "fas fa-terminal" >}} - To pull the NGINX Instance Manager 2.17.0 image, set the hostname to "mynim," and set the admin password to "abc123\!@", run: - - ```bash - docker run -it --rm \ - --hostname=mynim \ - -e NMS_PERSIST_DISABLE \ - -e NMS_ADMIN_PASSWORD="abc123\!@" \ - -p 8443:443 \ - private-registry.nginx.com/nms/nim-bundle:2.17.0 - ``` - - {{< /call-out >}} - -2. Upload the license: - - In a web browser, go to `https://:8443` and log in. Replace `` with the actual IP address or hostname of the machine running the Docker container. If you are accessing it locally, use `https://localhost:8443`. - - Select the **Settings** gear icon. - - On the **Settings** menu, select **Licenses**. - - Select **Get Started**. - - Select **Browse** to upload the license, or simply drag and drop the license onto the form. - - Select **Add**. -3. Close the browser to completely log off. -4. Stop and restart the container. -5. Log back in and verify that the license isn't applied. - ---- - -### Set up persistent storage - -1. Create or mount a directory for persistent storage to keep your data if the container restarts. -2. Run the following Docker command, replacing the placeholders with the appropriate values: - - ``: desired hostname - - ``: password for the admin account - - ``: path to the persistent data directory on the host machine - - ``: specific release version you want to use (**note:** `latest` is not supported) - - ```bash - docker run -it --rm \ - --hostname= \ - -e NMS_ADMIN_PASSWORD="" \ - --volume=:/data \ - -p 8443:443 \ - private-registry.nginx.com/nms/nim-bundle: - ``` - -
- - {{< call-out "tip" "Example:" "fas fa-terminal" >}} - To pull the NGINX Instance Manager 2.17.0 image, set the hostname to "mynim," set the admin password to "abc123\!@", and write data to `~/nms_storage`, run: - - ```bash - docker run -it --rm \ - --hostname=mynim \ - -e NMS_ADMIN_PASSWORD="abc123\!@" \ - --volume=/myvolume/nim-storage:/data \ - -p 8443:443 \ - private-registry.nginx.com/nms/nim-bundle:2.17.0 - ``` - - {{< /call-out >}} - -3. Upload the license: - - In a web browser, go to `https://:8443` and log in. Replace `` with the actual IP address or hostname of the machine running the Docker container. If you are accessing it locally, use `https://localhost:8443`. - - Select the **Settings** gear icon. - - On the Settings menu, select **Licenses**. - - Select **Get Started**. - - Select **Browse** to upload the license, or simply drag and drop the license onto the form. - - Select **Add**. - - Select **Done**. -4. Close the browser to completely log off. -5. Stop and restart the container. -6. Log back in and verify that the license is still applied. - ---- - -### Override self-signed API gateway certificates - -1. Ensure you have access to the required certificates: - - `mycert.pem` - - `mykey.pem` - - `myca.pem` - -2. Run the following Docker command, replacing the placeholders with the appropriate values: - - ``: desired hostname - - ``: password for the admin account - - ``: path to the persistent data directory on the host machine - - ``: specific release version you want to use (**Note:** `latest` is not supported) - - ```bash - docker run -it --rm \ - --hostname= \ - -e NMS_ADMIN_PASSWORD="" \ - -e NMS_APIGW_CERT="$(cat mycert.pem)" \ - -e NMS_APIGW_KEY="$(cat mykey.pem)" \ - -e NMS_APIGW_CA="$(cat myca.pem)" \ - --volume=:/data \ - -p 8443:443 private-registry.nginx.com/nms/nim-bundle: - ``` - -
- - {{< call-out "tip" "Example:" "far fa-terminal" >}} - To pull the NGINX Instance Manager 2.17.0 image, set the hostname to "mynim," use the password "abc123!@", pass in the certificates `mycert.pem`, `mykey.pem`, and `myca.pem`, and write data to `/myvolume/nim-storage`, run: - - ```bash - docker run -it --rm \ - --hostname=mynim \ - -e NMS_ADMIN_PASSWORD="abc123\!@" \ - -e NMS_APIGW_CERT="$(cat mycert.pem)" \ - -e NMS_APIGW_KEY="$(cat mykey.pem)" \ - -e NMS_APIGW_CA="$(cat myca.pem)" \ - --volume=/myvolume/nim-storage:/data \ - -p 8443:443 \ - private-registry.nginx.com/nms/nim-bundle:2.17.0 - ``` - - {{}} - -3. Log in and verify that the certificates are applied correctly. - - In a web browser, go to `https://:8443` and log in. Replace `` with the actual IP address or hostname of the machine running the Docker container. If you are accessing it locally, use `https://localhost:8443`. - ---- - -### Create and use an `.htpasswd` file - -In previous examples, the admin password was set using the `NMS_ADMIN_PASSWORD` environment variable. You can also set passwords for the admin and other users using an `.htpasswd` file. - -1. Create an `.htpasswd` file on the host machine with an admin user. You will be prompted to enter a password: - - ```bash - htpasswd -c .htpasswd admin - ``` - -2. To add more user passwords, use one of the following commands depending on the desired hashing method: - - {{< call-out "important" "Required: Create new users in the web interface" "fa-solid fa-circle-exclamation" >}} - Additional users must be created using the web interface first. If users are added only to the `.htpasswd` file and not in the web interface, they will not be able to log in. The web interface creates the users but doesn't support adding passwords, while the `.htpasswd` file adds the passwords but doesn't create the users. For instructions on adding users using the web interface, see [Creating Users]({{< relref "/nim/admin-guide/authentication/basic-auth/set-up-basic-authentication.md#create-users" >}}). - {{}} - - - For MD5 hash: - - ```bash - htpasswd -m .htpasswd user1 - ``` - - - For SHA hash: - - ```bash - htpasswd -s .htpasswd user2 - ``` - - {{}}NGINX does not support bcrypt password hashing.{{}} - -3. To pass the `.htpasswd` file at runtime, run the following command, replacing the placeholders with the appropriate values: - - ``: desired hostname - - ``: path to the directory containing the `.htpasswd` file on the host machine - - ``: path to the persistent data directory on the host machine - - ``: specific release version you want to use (**Note:** `latest` is not supported) - - ```bash - docker run -it --rm \ - --hostname= \ - --volume=/.htpasswd:/.htpasswd \ - --volume=:/data \ - -p 8443:443 private-registry.nginx.com/nms/nim-bundle: - ``` - - {{}}The admin user must be included in the `.htpasswd` file, or the container will not start.{{}} - -
- - {{< call-out "tip" "Example:" "far fa-terminal" >}} - To pull the NGINX Instance Manager 2.17.0 image, set the hostname to "mynim," pass in the `/myvolume/nim-auth/.htpasswd` file, and write data to `/myvolume/nim-storage`, run: - - ```bash - docker run -it --rm \ - --hostname=mynim \ - --volume=/myvolume/nim-auth/.htpasswd:/.htpasswd \ - --volume=/myvolume/nim-storage:/data \ - -p 8443:443 private-registry.nginx.com/nms/nim-bundle:2.17.0 - ``` - - {{}} - -4. To copy an updated `.htpasswd` file to a running container, use the following command, replacing the placeholders with the appropriate values: - - ``: path to the directory containing the `.htpasswd` file on the host machine - - ``: name of the running container - - ```bash - docker cp /.htpasswd :/data/local-auth/.htpasswd - ``` - -
- - {{< call-out "tip" "Example:" "far fa-terminal" >}} - - ```bash - docker cp /home/ubuntu/nim-auth/.htpasswd nginx-instance:/data/local-auth/.htpasswd - ``` - - {{}} - -
- - {{}} - To find a container's name, use the `docker ps` command, which lists all running containers along with their names. - {{}} - -5. Verify you can log in with the provided usernames and passwords. - - In a web browser, go to `https://:8443` and log in. Replace `` with the actual IP address or hostname of the machine running the Docker container. If you are accessing it locally, use `https://localhost:8443`. From f74f99abde4a4f2a3b12c938719711726a2d0e9b Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 25 Feb 2025 17:08:21 +0000 Subject: [PATCH 2/2] feat: Remove references to now deleted file --- content/nim/releases/release-notes.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/content/nim/releases/release-notes.md b/content/nim/releases/release-notes.md index 94383295e..7aec6ab7e 100644 --- a/content/nim/releases/release-notes.md +++ b/content/nim/releases/release-notes.md @@ -1,8 +1,10 @@ --- -docs: DOCS-938 title: Release Notes -toc: true weight: 100 +toc: true +type: reference +product: NIM +docs: DOCS-938 --- The release notes for F5 NGINX Instance Manager highlight the latest features, improvements, and bug fixes in each release. This document helps you stay up to date with the changes and enhancements introduced to improve stability, performance, and usability. For each version, you’ll find details about new features, known issues, and resolved problems, ensuring you get the most out of your NGINX instance management experience. @@ -146,8 +148,6 @@ This release includes the following updates: - {{% icon-feature %}} **Resilient Docker Compose NGINX Instance Manager deployment** - In 2.17, we released a [bundled container image]({{< relref "nim/deploy/docker/deploy-nginx-instance-manager-docker.md" >}}) with all NGINX Instance Manager components. While this is a great option for demos and lab environments, it is not the most fault-tolerant for production. - This [Docker Compose option]({{< relref "nim/deploy/docker/deploy-nginx-instance-manager-docker-compose.md" >}}) unlocks another easy, production-ready installation method for customers using Docker. It will also make upgrades easier when new Docker images are released by F5 NGINX. This option includes health checking, NGINX App Protect compilation support, and security monitoring. ### Changes in Default Behavior{#2-18-0-changes-in-behavior} @@ -314,8 +314,6 @@ This release includes the following updates: - {{% icon-feature %}} **Single docker image with all the NGINX Instance Manager services and dependencies** - This release includes access to a single Docker image for running NGINX Instance Manager as a container. This allows customers to deploy Instance Manager locally with a single "docker run" command. For more details, see [Deploy NGINX Instance Manager in a Single Docker Container]({{< relref "/nim/deploy/docker/deploy-nginx-instance-manager-docker.md" >}}). - ### Changes in Default Behavior{#2-17-0-changes-in-behavior} This release has the following changes in default behavior: