Add docs for installing nginx-agent from repository

README.md

@@ -64,8 +64,8 @@ NGINX Agent allows a gRPC connected control system to register a listener for a
 
 | Event                            | Description                                  |
 | -------------------------------- | -------------------------------------------- |
-| AGENT_START_MESSAGE              | NGINX Agent process started                        |
-| AGENT_STOP_MESSAGE               | NGINX Agent process stopped                        |
+| AGENT_START_MESSAGE              | NGINX Agent process started                  |
+| AGENT_STOP_MESSAGE               | NGINX Agent process stopped                  |
 | NGINX_FOUND_MESSAGE              | NGINX master process detected on system      |
 | NGINX_STOP_MESSAGE               | NGINX master process stopped                 |
 | NGINX_RELOAD_SUCCESS_MESSAGE     | NGINX master process reloaded successfully   |

hugo/content/changelog.md

@@ -2,7 +2,7 @@
 title: "Changelog"
 draft: false
 description: "NGINX Agent updates changelog."
-weight: 700
+weight: 900
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1093"

hugo/content/community.md

@@ -2,7 +2,7 @@
 title: "Contributing and Support"
 draft: false
 description: "Learn about the NGINX Agent community."
-weight: 600
+weight: 800
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1087"

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: 400
+weight: 600
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1088"
@@ -16,7 +16,7 @@ While most Linux or FreeBSD operating systems can be used to contribute to the N
 
 ## Install NGINX
 
-Follow the steps in the [Installation]({{< relref "/installation.md" >}}) section to download, install, and run NGINX and NGINX Agent.
+Follow the steps in the [Installation]({{< relref "/installation-github.md" >}}) section to download, install, and run NGINX and NGINX Agent.
 
 ## Clone the NGINX Agent Repository
 
@@ -56,7 +56,7 @@ make install-tools deps
 
 Run the following commands to build and run NGINX Agent:
 
-```
+```bash
 make build
 sudo make run
 ```

hugo/content/getting-started.md

@@ -2,7 +2,7 @@
 title: "Getting Started"
 draft: false
 description: "Learn how to configure and run NGINX Agent."
-weight: 300
+weight: 500
 toc: true
 tags: [ "docs" ]
 docs: "DOCS-1089"
@@ -14,7 +14,7 @@ Follow these steps to configure and run NGINX Agent and a mock interface ("contr
 
 ## Install NGINX
 
-Follow the steps in the [Installation]({{< relref "/installation.md" >}}) section to download, install, and run NGINX.
+Follow the steps in the [Installation]({{< relref "/installation-github.md" >}}) section to download, install, and run NGINX.
 
 ## Clone the NGINX Agent Repository
 
@@ -139,3 +139,23 @@ Open a web browser to view the mock control plane at [http://localhost:54790](ht
 - **metrics** - shows a buffer of metrics sent to the management plane (similar to what will be sent back in the REST API)
 
 For more NGINX Agent use cases, refer to the [NGINX Agent SDK examples](https://github.com/nginx/agent/tree/main/sdk/examples).
+
+## Start and Enable Start on Boot
+
+To start the NGINX Agent on `systemd` systems, run the following command:
+
+```
+sudo systemctl start nginx-agent
+```
+
+To enable the NGINX Agent to start on boot, run the following command:
+
+```
+sudo systemctl enable nginx-agent
+```
+
+## Logs 
+
+NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of the NGINX Agent log files. We recommend adding a separate partition for `/var/log/nginx-agent`. 
+
+{{< important >}}Without log rotation or storage on a separate partition, log files could use up all the free drive space and cause your system to become unresponsive to certain services.{{< /important >}}

hugo/content/installation.md → hugo/content/installation-github.md

@@ -1,7 +1,7 @@
 ---
-title: "Installation"
+title: "Installation from GitHub Release"
 draft: false
-description: "Learn how to install NGINX Agent."
+description: "Learn how to install NGINX Agent from GitHub Release."
 weight: 200
 toc: true
 tags: [ "docs" ]
@@ -14,9 +14,9 @@ doctypes: ["task"]
 
 NGINX Agent interfaces directly with an NGINX server process installed on the same system. If you don't have it already, follow these steps to install [NGINX Open Source](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/) or [NGINX Plus](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-plus/). Once installed, ensure the NGINX instance is running.
 
-## Install Agent from Package Files
+## Install NGINX Agent from Package Files
 
-To install NGINX Agent on your system, go to [Releases](https://github.com/nginx/agent/releases) and download the latest package supported by your OS distribution and CPU architecture.
+To install NGINX Agent on your system, go to [GitHub Releases](https://github.com/nginx/agent/releases) and download the latest package supported by your OS distribution and CPU architecture.
 
 Use your system's package manager to install the package. Some examples:
 
@@ -49,23 +49,3 @@ Use your system's package manager to install the package. Some examples:
   ```
   sudo pkg add nginx-agent-<agent-version>.pkg
   ```
-
-## Start and Enable Start on Boot
-
-To start the NGINX Agent on `systemd` systems, run the following command:
-
-```
-sudo systemctl start nginx-agent
-```
-
-To enable the NGINX Agent to start on boot, run the following command:
-
-```
-sudo systemctl enable nginx-agent
-```
-
-## Logs 
-
-NGINX Agent uses formatted log files to collect metrics. Expanding log formats and instance counts will also increase the size of the NGINX Agent log files. We recommend adding a separate partition for `/var/log/nginx-agent`. 
-
-{{< important >}}Without log rotation or storage on a separate partition, log files could use up all the free drive space and cause your system to become unresponsive to certain services.{{< /important >}}

hugo/content/installation-oss.md

@@ -0,0 +1,221 @@
+---
+title: "Installation From NGINX Repository"
+draft: false
+description: "Learn how to install NGINX Agent from OSS Repository."
+weight: 300
+toc: true
+tags: [ "docs" ]
+docs: "DOCS-1091"
+categories: ["configuration"]
+doctypes: ["task"]
+---
+
+## Install NGINX
+
+NGINX Agent interfaces directly with an NGINX server process installed on the same system. If you don't have it already, follow these steps to install [NGINX Open Source](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/). Once installed, ensure the NGINX instance is running.
+
+## Install NGINX Agent from NGINX Repository
+
+First ensure that you are running a supported distribution and architecture: [technical specifications](../technical-specifications/)
+
+Before you install NGINX Agent for the first time on your system, you need to set up the nginx-agent packages repository. Afterward, you can install and update nginx agent from the repository.
+
+- [RHEL, CentOS, Rocky Linux, AlmaLinux and Oracle Linux](#rhel-centos-rocky-linux-almalinux-and-oracle-linux)
+- [Ubuntu](#ubuntu)
+- [Debian](#debian)
+- [SLES](#sles)
+- [Alpine Linux](#alpine-linux)
+- [Amazon Linux](#amazon-linux)
+
+### RHEL, CentOS, Rocky Linux, AlmaLinux and Oracle Linux
+  - Install the prerequisites:
+    ```
+    sudo yum install yum-utils
+    ```
+
+  - To set up the yum repository, create the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents:
+    ```
+    [nginx-agent]
+    name=nginx agent repo
+    baseurl=http://packages.nginx.org/nginx-agent/centos/$releasever/$basearch/
+    gpgcheck=1
+    enabled=1
+    gpgkey=https://nginx.org/keys/nginx_signing.key
+    module_hotfixes=true
+    ```
+
+  - To install nginx agent, run the following command:
+    ```
+    sudo yum install nginx-agent
+    ```
+    When prompted to accept the GPG key, verify that the fingerprint matches `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, and if so, accept it.
+
+### Ubuntu
+  - Add the nginx agent repository:
+    ```
+    echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
+      http://packages.nginx.org/nginx-agent/ubuntu/ `lsb_release -cs` agent" \
+      | sudo tee /etc/apt/sources.list.d/nginx-agent.list
+    ```
+
+### Debian
+  - Install the prerequisites:
+    ```
+    sudo apt install curl gnupg2 ca-certificates lsb-release debian-archive-keyring
+    ```
+
+  - Import an official nginx signing key so apt could verify the packages authenticity. Fetch the key:
+    ```
+    curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \
+        | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null
+    ```
+
+  - Verify that the downloaded file contains the proper key:
+    ```
+    gpg --dry-run --quiet --no-keyring \
+      --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg
+    ```
+
+    The output should contain the full fingerprint 573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62 as follows:
+    ```
+    pub   rsa2048 2011-08-19 [SC] [expires: 2024-06-14]
+          573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
+    uid                      nginx signing key <[email protected]>
+    ```
+    {{< important >}}If the fingerprint is different, remove the file.{{< /important >}}
+
+  - Add the `nginx-agent` repository:
+    ```
+    echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
+      http://packages.nginx.org/nginx-agent/debian/ `lsb_release -cs` agent" \ | sudo tee /etc/apt/sources.list.d/nginx-agent.list
+    ```
+
+  - To install `nginx-agent`, run the following commands:
+    ```
+    sudo apt update
+    sudo apt install nginx-agent
+    ```
+
+### SLES
+  - Install the prerequisites:
+    ```
+    sudo zypper install curl ca-certificates gpg2
+    ```
+
+  - To set up the zypper repository for `nginx-agent` packages, run the following command:
+    ```
+    sudo zypper addrepo --gpgcheck --refresh --check \
+        'http://packages.nginx.org/nginx-agent/sles/$releasever_major' nginx-agent
+    ```
+
+  - Next, import an official nginx signing key so `zypper`/`rpm` could verify the packages authenticity. Fetch the key:
+    ```
+    curl -o /tmp/nginx_signing.key https://nginx.org/keys/nginx_signing.key
+    ```
+
+  - Verify that the downloaded file contains the proper key:
+    ```
+    gpg --with-fingerprint /tmp/nginx_signing.key
+    ```
+
+  - The output should contain the full fingerprint `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62` as follows:
+    ```
+    pub  2048R/7BD9BF62 2011-08-19 [expires: 2024-06-14]
+          Key fingerprint = 573B FD6B 3D8F BC64 1079  A6AB ABF5 BD82 7BD9 BF62
+    uid nginx signing key <[email protected]>
+    ```
+
+  - Finally, import the key to the rpm database:
+    ```
+    sudo rpmkeys --import /tmp/nginx_signing.key
+    ```
+
+  - To install `nginx-agent`, run the following command:
+    ```
+    sudo zypper install nginx-agent
+    ```
+
+### Alpine Linux
+  - Install the prerequisites:
+    ```
+    sudo apk add openssl curl ca-certificates
+    ```
+
+  - To set up the apk repository for `nginx-agent` packages, run the following command:
+    ```
+    printf "%s%s%s%s\n" \
+        "@nginx-agent " \
+        "http://packages.nginx.org/nginx-agent/alpine/v" \
+        `grep -o -E '^[0-9]+\.[0-9]+' /etc/alpine-release` \
+        "/main" \
+        | sudo tee -a /etc/apk/repositories
+    ```
+
+  - Next, import an official nginx signing key so apk could verify the packages authenticity. Fetch the key:
+    ```
+    curl -o /tmp/nginx_signing.rsa.pub https://nginx.org/keys/nginx_signing.rsa.pub
+    ```
+
+  - Verify that downloaded file contains the proper key:
+    ```
+    openssl rsa -pubin -in /tmp/nginx_signing.rsa.pub -text -noout
+    ```
+
+    The output should contain the following modulus:
+    ```
+    Public-Key: (2048 bit)
+    Modulus:
+        00:fe:14:f6:0a:1a:b8:86:19:fe:cd:ab:02:9f:58:
+        2f:37:70:15:74:d6:06:9b:81:55:90:99:96:cc:70:
+        5c:de:5b:e8:4c:b2:0c:47:5b:a8:a2:98:3d:11:b1:
+        f6:7d:a0:46:df:24:23:c6:d0:24:52:67:ba:69:ab:
+        9a:4a:6a:66:2c:db:e1:09:f1:0d:b2:b0:e1:47:1f:
+        0a:46:ac:0d:82:f3:3c:8d:02:ce:08:43:19:d9:64:
+        86:c4:4e:07:12:c0:5b:43:ba:7d:17:8a:a3:f0:3d:
+        98:32:b9:75:66:f4:f0:1b:2d:94:5b:7c:1c:e6:f3:
+        04:7f:dd:25:b2:82:a6:41:04:b7:50:93:94:c4:7c:
+        34:7e:12:7c:bf:33:54:55:47:8c:42:94:40:8e:34:
+        5f:54:04:1d:9e:8c:57:48:d4:b0:f8:e4:03:db:3f:
+        68:6c:37:fa:62:14:1c:94:d6:de:f2:2b:68:29:17:
+        24:6d:f7:b5:b3:18:79:fd:31:5e:7f:4c:be:c0:99:
+        13:cc:e2:97:2b:dc:96:9c:9a:d0:a7:c5:77:82:67:
+        c9:cb:a9:e7:68:4a:e1:c5:ba:1c:32:0e:79:40:6e:
+        ef:08:d7:a3:b9:5d:1a:df:ce:1a:c7:44:91:4c:d4:
+        99:c8:88:69:b3:66:2e:b3:06:f1:f4:22:d7:f2:5f:
+        ab:6d
+    Exponent: 65537 (0x10001)
+    ```
+
+  - Finally, move the key to apk trusted keys storage:
+    ```
+    sudo mv /tmp/nginx_signing.rsa.pub /etc/apk/keys/
+    ```
+
+  - To install nginx-agent, run the following command:
+    ```
+    sudo apk add nginx-agent@nginx-agent
+    ```
+
+### Amazon Linux
+  - Install the prerequisites:
+    ```
+    sudo yum install yum-utils procps
+    ```
+
+  - To set up the yum repository for Amazon Linux 2, create the file named `/etc/yum.repos.d/nginx-agent.repo` with the following contents:
+    ```
+    [nginx-agent]
+    name=nginx agent repo
+    baseurl=http://packages.nginx.org/nginx-agent/amzn2/$releasever/$basearch/
+    gpgcheck=1
+    enabled=1
+    gpgkey=https://nginx.org/keys/nginx_signing.key
+    module_hotfixes=true
+    ```
+
+  - To install nginx, run the following command:
+    ```
+    sudo yum install nginx-agent
+    ```
+
+  - When prompted to accept the GPG key, verify that the fingerprint matches `573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62`, and if so, accept it.