Add documentation for docker images (#418)

nginx · Aug 4, 2023 · 8888428 · 8888428
1 parent 0f149a8
commit 8888428
Show file tree

Hide file tree

Showing 12 changed files with 91 additions and 12 deletions.
diff --git a/README.md b/README.md
@@ -18,6 +18,7 @@ NGINX Agent is a companion daemon for your NGINX Open Source or NGINX Plus insta
   - [Installing NGINX Agent from Package Files](#installing-nginx-agent-from-package-files)
   - [Starting and Enabling Start on Boot](#starting-and-enabling-start-on-boot)
   - [Logging](#logging)
+  - [Building Docker Image](#building-docker-image)
 - [Getting Started with NGINX Agent](#getting-started-with-nginx-agent)
   - [Installing NGINX](#installing-nginx)
   - [Cloning the NGINX Agent Repository](#cloning-the-nginx-agent-repository)
@@ -150,6 +151,14 @@ If you need to make changes to the default configuration you can update the file
 
 For more detail on logrotate configuration see [Logrotate Configuration Options](https://linux.die.net/man/8/logrotate)
 
+## Building Docker Image
+To build an image that contains the latest NGINX Agent and the latest mainline version of NGINX OSS run the following command:
+```
+make official-oss-image
+```
+
+For more information on how to run NGINX Agent containers and how build an image that uses NGINX Plus instead of NGINX OSS see [Docker Images](https://docs.nginx.com/nginx-agent/docker-images/)
+
 # Getting Started with NGINX Agent
 Follow these steps to configure and run NGINX Agent and a mock interface ("control plane") to which the NGINX Agent will report.
 

diff --git a/hugo/content/changelog.md b/hugo/content/changelog.md
@@ -2,7 +2,7 @@
 title: "Changelog"
 draft: false
 description: "NGINX Agent updates changelog."
-weight: 1100
+weight: 1200
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1093"

diff --git a/hugo/content/community.md b/hugo/content/community.md
@@ -2,7 +2,7 @@
 title: "Contributing and Support"
 draft: false
 description: "Learn about the NGINX Agent community."
-weight: 900
+weight: 1000
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1087"

diff --git a/hugo/content/configuration-overview.md b/hugo/content/configuration-overview.md
@@ -2,7 +2,7 @@
 title: "Configuration Overview"
 draft: false
 description: "Learn the overview of configuration"
-weight: 500
+weight: 800
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1229"
@@ -268,4 +268,4 @@ By default, NGINX Agent rotates logs daily using logrotate with the following co
 
 If you need to make changes to the default configuration you can update the file here `/etc/logrotate.d/nginx-agent`
 
-For more detail on logrotate configuration see [Logrotate Configuration Options](https://linux.die.net/man/8/logrotate)
+For more detail on logrotate configuration see [Logrotate Configuration Options](https://linux.die.net/man/8/logrotate)
diff --git a/hugo/content/dev-environment-setup.md b/hugo/content/dev-environment-setup.md
@@ -2,7 +2,7 @@
 title: "Development Environment Setup"
 draft: false
 description: "Learn how to setup a Development Environment for NGINX Agent."
-weight: 800
+weight: 900
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1088"

diff --git a/hugo/content/docker-images.md b/hugo/content/docker-images.md
@@ -0,0 +1,70 @@
+---
+title: "Docker Images"
+draft: false
+description: "Learn how to build and run NGINX Agent docker images"
+weight: 800
+toc: true
+tags: [ "docs" ]
+categories: ["configuration"]
+doctypes: ["task"]
+---
+
+## Prerequisites
+1. Docker must be [installed and running](https://docs.docker.com/engine/install/)
+1. (Optional) If you plan to use NGINX Plus, you will need the nginx-repo.crt and nginx-repo.key files. You can download them from [MyF5](https://my.f5.com).
+
+## Building NGINX Agent image with NGINX Open Source
+
+To build an image that contains the latest NGINX Agent and the latest mainline version of NGINX run the following command:
+
+```shell
+$ cd scripts/docker/official/nginx-oss-with-nginx-agent/alpine/
+$ docker build -t nginx-agent . --no-cache -f ./Dockerfile.mainline
+```
+
+To build an image that contains the latest NGINX Agent and the latest stable version of NGINX run the following command:
+```shell
+$ cd scripts/docker/official/nginx-oss-with-nginx-agent/alpine/
+$ docker build -t nginx-agent . --no-cache -f ./Dockerfile.stable
+```
+
+## Building NGINX Agent image with NGINX Plus
+
+1. Log in to [MyF5 Customer Portal](https://account.f5.com/myf5) and download your `nginx-repo.crt` and `nginx-repo.key` files. These files are also provided with the NGINX Plus trial package.
+
+1. Copy the files to the directory where the Dockerfile is located `scripts/docker/official/nginx-plus-with-nginx-agent/alpine/`.
+
+1. To build an image that contains the latest NGINX Agent and the latest version of NGINX Plus run the following command:
+
+```shell
+$ cd scripts/docker/official/nginx-plus-with-nginx-agent/alpine/
+$ docker build -t nginx-agent . \
+  --no-cache -f ./Dockerfile \
+  --secret id=nginx-crt,src=nginx-repo.crt \
+  --secret id=nginx-key,src=nginx-repo.key
+```
+
+## Running NGINX Agent container
+
+Here is an example of how to run a NGINX Agent container:
+
+```console
+$ docker run --name nginx-agent -d nginx-agent
+```
+
+By default, the NGINX Agent REST API is not enabled. To enable the API, the NGINX Agent configuration file `nginx-agent.conf` needs to be updated to include the API configuration, for example:
+
+```yaml
+api:
+  host: 0.0.0.0
+  port: 8038
+```
+
+Once the `nginx-agent.conf` file is updated with the API setting, following the previous example, you can run the container with the updated `nginx-agent.conf` mounted and the port `8038` exposed with the following command:
+
+```console
+$ docker run --name nginx-agent -d \
+  --mount type=bind,source="$(pwd)"/nginx-agent.conf,target=/etc/nginx-agent/nginx-agent.conf,readonly \
+  -p 127.0.0.1:8038:8038/tcp \
+  nginx-agent
+```
diff --git a/hugo/content/getting-started.md b/hugo/content/getting-started.md
@@ -2,7 +2,7 @@
 title: "Getting Started"
 draft: false
 description: "Learn how to configure and run NGINX Agent."
-weight: 700
+weight: 200
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1089"

diff --git a/hugo/content/installation-github.md b/hugo/content/installation-github.md
@@ -2,7 +2,7 @@
 title: "Installation from GitHub Release"
 draft: false
 description: "Learn how to install NGINX Agent from a GitHub Release."
-weight: 200
+weight: 300
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1090"

diff --git a/hugo/content/installation-oss.md b/hugo/content/installation-oss.md
@@ -2,7 +2,7 @@
 title: "Installation From NGINX Repository"
 draft: false
 description: "Learn how to install NGINX Agent from OSS Repository."
-weight: 300
+weight: 400
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1216"

diff --git a/hugo/content/installation-plus.md b/hugo/content/installation-plus.md
@@ -2,7 +2,7 @@
 title: "Installation from NGINX Plus Repository"
 draft: false
 description: "Learn how to install NGINX Agent from NGINX Plus repository."
-weight: 400
+weight: 500
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1217"

diff --git a/hugo/content/technical-specifications.md b/hugo/content/technical-specifications.md
@@ -2,7 +2,7 @@
 title: "Technical Specifications"
 draft: false
 description: "This document describes the requirements for NGINX Agent."
-weight: 1000
+weight: 1100
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1092"

diff --git a/hugo/content/uninstall.md b/hugo/content/uninstall.md
@@ -2,7 +2,7 @@
 title: "Uninstall NGINX Agent Package"
 draft: false
 description: "Learn how to uninstall NGINX Agent"
-weight: 500
+weight: 700
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1230"
@@ -141,4 +141,4 @@ Complete the following steps on each host where you've installed the NGINX Agent
 
    ```bash
    sudo pkg delete nginx-agent
-   ``` 
+   ```