Build container images

Overview

NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instances and must run in the same container to work. The NGINX Agent GitHub repository includes Dockerfiles that you can use to build custom container images that bundle NGINX Agent with NGINX or NGINX Plus.

If you want to use NGINX Agent with NGINX Plus, you need to purchase an NGINX Plus license. Contact your F5 Sales representative for assistance.

See the requirements and supported operating systems in the NGINX Agent Technical Specifications topic.

Deploy Offical NGINX and NGINX Plus Containers

Docker images are available in the Deploying NGINX and NGINX Plus on Docker NGINX documentation.

This guide provides instructions on how to build images with NGINX Agent and NGINX packaged together. It includes steps for downloading the necessary Docker images, configuring your Docker environment, and deploying NGINX and NGINX Plus containers.

Set up your environment

Install a container engine

You can use Docker or Podman to manage NGINX Agent container images. Follow the installation instructions for your preferred container engine and be sure the service is running before proceeding with the instructions in this document.

Note:
The examples in this document primarily use Docker commands. You can adapt these using the appropriate Podman commands if you’re not using Docker.

Install the GNU Make package

You need to use the GNU Make package to build the NGINX Agent container images provided in the nginx-agent GitHub repository.

If you do not already have Make installed, install it using the appropriate package manager for your operating system.

For example, to install make using the Ubuntu Advanced Packaging Tool (APT), run the command apt install command shown in the example. In some cases, it may help to update the package source lists in your operating system before proceeding.

1. Update the package source list:

   sudo apt update
   

2. Install the make package:

   sudo apt install make
   

Clone the nginx-agent repository

The NGINX Agent GitHub repo contains the Dockerfiles and supporting scripts that you will use to build your images.

Run the appropriate command below to clone the GitHub repo by using HTTPS or SSH.

• HTTPS
• SSH

git clone https://github.com/nginx/agent.git

git clone git@github.com:nginx/agent.git

Download the NGINX Plus certificate and key

This step is required if you are using NGINX Plus. If you are using NGINX open source, you can skip this section.

In order to build a container image with NGINX Plus, you must provide the SSL certificate and private key files provided with your NGINX Plus license. These files grant access to the package repository from which the script will download the NGINX Plus package.

1. Log in to the MyF5 customer portal.

2. Go to My Products and Plans > Subscriptions.

3. Select the product subscription.

4. Download the SSL Certificate and Private Key files.

5. Move the SSL certificate and private key files to the directory where you cloned the nginx-agent repo.

   • The Makefile expects to find these files in the path ./build/certs. Assuming you cloned the nginx-agent repo to your $HOME directory, you would move and rename the files as follows:

     mkdir -p $HOME/nginx-agent/build/certs
     mv nginx-repo-S-X00012345.key $HOME/nginx-agent/build/certs/nginx-repo.key
     mv nginx-repo-S-X00012345.crt $HOME/nginx-agent/build/certs/nginx-repo.crt
     

   • Be sure to replace the example certificate and key filenames shown in the example command with your actual file names.

   • The file names in the build/certs directory must match those shown in the example.

Run the NGINX Agent container

To run NGINX Agent container using Docker use the following command:

docker pull docker-registry.nginx.com/nginx/agent:mainline

docker tag docker-registry.nginx.com/nginx/agent:mainline nginx-agent

docker run --name nginx-agent -d nginx-agent

Note:
To learn more about the configuration options, refer to the NGINX Agent Configuration Overview.

Enable the gRPC interface

To connect your NGINX Agent container to your NGINX One or NGINX Instance Manager instance, you must enable the gRPC interface. To do this, you must edit the NGINX Agent configuration file, nginx-agent.conf. For example:

server:
  host: 127.0.0.1 # mock control plane host
  grpcPort: 54789 # mock control plane gRPC port

# gRPC TLS options - DISABLING TLS IS NOT RECOMMENDED FOR PRODUCTION
tls:
  enable: false
  skip_verify: true

Enable the REST interface

If your control plane requires REST API, you can expose NGINX Agent’s REST API by editing the NGINX Agent configuration file, nginx-agent.conf. For example:

api:
  host: 0.0.0.0
  port: 8038

Once you have updated the nginx-agent.conf file, you can run the container with the updated nginx-agent.conf mounted and the port 8038 exposed with the following command:

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

To ensure that the REST Interface is correctly configured, you can use the curl command targeting the following endpoint from your terminal:

curl 0.0.0.0:8038/nginx/

If the REST Interface is configured correctly, then you should see a JSON object ouputted to the terminal containing metadata such as NGINX version, path to the NGINX conf, and runtime modules.

Sample Output:

[{"nginx_id":"b636d4376dea15405589692d3c5d3869ff3a9b26b0e7bb4bb1aa7e658ace1437","version":"1.27.1","conf_path":"/etc/nginx/nginx.conf","process_id":"7","process_path":"/usr/sbin/nginx","start_time":1725878806000,"built_from_source":false,"loadable_modules":null,"runtime_modules":["http_addition_module","http_auth_request_module","http_dav_module","http_flv_module","http_gunzip_module","http_gzip_static_module","http_mp4_module","http_random_index_module","http_realip_module","http_secure_link_module","http_slice_module","http_ssl_module","http_stub_status_module","http_sub_module","http_v2_module","http_v3_module","mail_ssl_module","stream_realip_module","stream_ssl_module","stream_ssl_preread_module"],"plus":{"enabled":false,"release":""},"ssl":{"ssl_type":0,"details":["OpenSSL","3.3.0","9 Apr 2024 (running with OpenSSL 3.3.1 4 Jun 2024)"]},"status_url":"","configure_args":["","prefix=/etc/nginx","sbin-path=/usr/sbin/nginx","modules-path=/usr/lib/nginx/modules","conf-path=/etc/nginx/nginx.conf","error-log-path=/var/log/nginx/error.log","http-log-path=/var/log/nginx/access.log","pid-path=/var/run/nginx.pid","lock-path=/var/run/nginx.lock","http-client-body-temp-path=/var/cache/nginx/client_temp","http-proxy-temp-path=/var/cache/nginx/proxy_temp","http-fastcgi-temp-path=/var/cache/nginx/fastcgi_temp","http-uwsgi-temp-path=/var/cache/nginx/uwsgi_temp","http-scgi-temp-path=/var/cache/nginx/scgi_temp","with-perl_modules_path=/usr/lib/perl5/vendor_perl","user=nginx","group=nginx","with-compat","with-file-aio","with-threads","with-http_addition_module","with-http_auth_request_module","with-http_dav_module","with-http_flv_module","with-http_gunzip_module","with-http_gzip_static_module","with-http_mp4_module","with-http_random_index_module","with-http_realip_module","with-http_secure_link_module","with-http_slice_module","with-http_ssl_module","with-http_stub_status_module","with-http_sub_module","with-http_v2_module","with-http_v3_module","with-mail","with-mail_ssl_module","with-stream","with-stream_realip_module","with-stream_ssl_module","with-stream_ssl_preread_module","with-cc-opt='-Os -fstack-clash-protection -Wformat -Werror=format-security -g'","with-ld-opt=-Wl,--as-needed,-O1,--sort-common"],"error_log_paths":null}]

Build the NGINX Agent images for specific OS targets

Important:
The only officially supported base operating system is Alpine. The instructions below for other operating systems are provided for informational and testing purposes only.

The NGINX Agent GitHub repo has a set of Make commands that you can use to build a container image for an specific operating system and version:

• make oss-image builds an image containing NGINX Agent and NGINX open source.
• make image builds an image containing NGINX Agent and NGINX Plus.

You can pass the following arguments when running the make command to build an NGINX Agent container image.

Refer to the Supported distributions table to find out which base images you can use. You can find the official images and versions for each distribution on Docker Hub.

Keep the following information in mind when using the NGINX Agent Dockerfiles to build container images:

• On some operating systems, you need root privileges (sudo) to run make commands.
• If you choose to run the docker build or podman build command instead of using the make commands provided, you must do so from the nginx-agent repository’s root directory.

Build NGINX open source images

Run the following make command to build the default image, which uses Alpine as the base image:

IMAGE_BUILD_TARGET=install-agent-repo make oss-image

To build an image with Debian and an older version of NGINX Agent you can run the following command:

IMAGE_BUILD_TARGET=install-agent-repo NGINX_AGENT_VERSION=2.37.0~bullseye OS_RELEASE=debian OS_VERSION=bullseye-slim make oss-image

Build NGINX Plus images

Important:
You need a license to use NGINX Agent with NGINX Plus. You must complete the steps in the Download the certificate and key files from MyF5 section before proceeding.

Run the following make command to build the default image, which uses Ubuntu 24.04 (Noble) as the base image.

IMAGE_BUILD_TARGET=install-agent-repo make image

To build an image with Debian and an older version of NGINX Agent you can run the following command:

IMAGE_BUILD_TARGET=install-agent-repo NGINX_AGENT_VERSION=2.37.0~bullseye OS_RELEASE=debian OS_VERSION=bullseye-slim make image