Migrate with Docker Compose

Before you begin

  • Ensure you have:
    • Docker compose installed
    • Registry credentials (if required)
    • NGINX_LICENSE_JWT and the NGINX Agent command auth token (data plane key)
  • Back up your existing docker-compose.yaml.
  • Plan a maintenance window and test this procedure in a non‑production environment first.
Do not run v2 and v3 concurrently
Do not run NGINX Agent v2 and v3 concurrently in the same container or on the same host.

Migrate

  1. Update your compose file to use the v3 image and environment variables. Example:

    yaml
    version: "3.8"
services:
  nginx-agent:
    image: <registry>/nginx-plus/agent/debian:<v3-tag>
    environment:
      NGINX_AGENT_COMMAND_SERVER_HOST: agent.connect.nginx.com
      NGINX_AGENT_COMMAND_SERVER_PORT: "443"
      NGINX_AGENT_COMMAND_TLS_SKIP_VERIFY: "false"
      NGINX_AGENT_COMMAND_AUTH_TOKEN: ${NGINX_AGENT_COMMAND_AUTH_TOKEN}
      NGINX_LICENSE_JWT: ${NGINX_LICENSE_JWT}
      # Optional: If using Config Sync Groups
      # NGINX_AGENT_LABELS: config-sync-group=<config-sync-group-name>

  2. Restart the service:

    shell
    docker compose down
docker compose up -d

  3. Validate the migration:

    docker logs <nginx-agent-container-name>
    • Look for: msg="Agent connected"
    • Verify the instance is Online in the NGINX One Console.

Rollback

  • Restore the previous docker-compose.yaml and run: 
    docker compose down && docker compose up -d

References

View source
Edit this page
Create a new issue