From 88884283eccfea35a9f80c78a476d027c1e8ea42 Mon Sep 17 00:00:00 2001 From: Donal Hurley Date: Fri, 4 Aug 2023 14:40:22 +0100 Subject: [PATCH] Add documentation for docker images (#418) --- README.md | 9 +++ hugo/content/changelog.md | 2 +- hugo/content/community.md | 2 +- hugo/content/configuration-overview.md | 4 +- hugo/content/dev-environment-setup.md | 2 +- hugo/content/docker-images.md | 70 ++++++++++++++++++++++++ hugo/content/getting-started.md | 2 +- hugo/content/installation-github.md | 2 +- hugo/content/installation-oss.md | 2 +- hugo/content/installation-plus.md | 2 +- hugo/content/technical-specifications.md | 2 +- hugo/content/uninstall.md | 4 +- 12 files changed, 91 insertions(+), 12 deletions(-) create mode 100644 hugo/content/docker-images.md diff --git a/README.md b/README.md index ed6c2a2126..e87a6d8858 100644 --- 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 index 1f29daa6de..2db61fca92 100644 --- 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 index 460385fcbd..22890eaca4 100644 --- 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 index 60c6d70b00..141ca32295 100644 --- 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) \ No newline at end of file +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 index 7fd520d13a..385a882fef 100644 --- 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 new file mode 100644 index 0000000000..ba8c680113 --- /dev/null +++ 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 index 1be99b7e83..3034590191 100644 --- 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 index cba2afe943..0be3c80cda 100644 --- 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 index d661c92d21..097d6c4d62 100644 --- 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 index 65ec89f659..6a49aece39 100644 --- 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 index 1dfddf61fe..4a50ea5a58 100644 --- 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 index 5479d0d19d..4adb2a6ff4 100644 --- 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 - ``` \ No newline at end of file + ```