{"id":28004025,"url":"https://github.com/fabriziofiorucci/nginx-nim-docker","last_synced_at":"2025-05-09T02:44:06.456Z","repository":{"id":62995772,"uuid":"441331832","full_name":"fabriziofiorucci/NGINX-NIM-Docker","owner":"fabriziofiorucci","description":"This repository creates a docker image for NGINX Instance Manager to run it on Kubernetes, Openshift and docker-compose. Optional integration with Second Sight.","archived":false,"fork":false,"pushed_at":"2025-03-11T14:02:05.000Z","size":2100,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-20T12:41:16.374Z","etag":null,"topics":["kubernetes","nginx","nginx-instance-manager","security-monitoring"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabriziofiorucci.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-12-24T01:04:12.000Z","updated_at":"2025-03-11T14:02:09.000Z","dependencies_parsed_at":"2024-04-18T11:54:03.775Z","dependency_job_id":"12bbf595-b104-4c16-99f6-71dea70b650f","html_url":"https://github.com/fabriziofiorucci/NGINX-NIM-Docker","commit_stats":null,"previous_names":["fabriziofiorucci/nginx-nim-docker"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziofiorucci%2FNGINX-NIM-Docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziofiorucci%2FNGINX-NIM-Docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziofiorucci%2FNGINX-NIM-Docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriziofiorucci%2FNGINX-NIM-Docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabriziofiorucci","download_url":"https://codeload.github.com/fabriziofiorucci/NGINX-NIM-Docker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253180885,"owners_count":21866988,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kubernetes","nginx","nginx-instance-manager","security-monitoring"],"created_at":"2025-05-09T02:44:05.844Z","updated_at":"2025-05-09T02:44:06.447Z","avatar_url":"https://github.com/fabriziofiorucci.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NGINX Instance Manager for Docker\n\nThis repository helps deploying NGINX Instance Manager on containerized clusters by creating a docker image.\n\nIt is also available as part of [official NGINX Demos](https://github.com/nginxinc/NGINX-Demos/tree/master/nginx-nim-docker)\n\n## Docker image creation\n\nDocker image creation is supported for:\n\n- [NGINX Instance Manager](https://docs.nginx.com/nginx-instance-manager/) 2.4.0+\n- [Security Monitoring](https://docs.nginx.com/nginx-management-suite/security/) 1.0.0+\n- [NGINX App Protect WAF compiler](https://docs.nginx.com/nginx-management-suite/nim/how-to/app-protect/setup-waf-config-management)\n\nThe image can optionally be built with [Second Sight](https://github.com/F5Networks/SecondSight) support\n\n## Tested releases\n\nThis repository has been tested on `amd64` and `arm64` architectures with:\n\n- NGINX Instance Manager 2.4.0+\n- Security Monitoring 1.0.0+\n- NGINX App Protect WAF compiler v3.1088.2+\n\n## Prerequisites\n\nThis repository has been tested with:\n\n- Docker 20.10+ to build the image\n- Private registry to push the target Docker image\n- Kubernetes cluster with dynamic storage provisioner enabled: see the [example](contrib/pvc-provisioner)\n- NGINX Ingress Controller with `VirtualServer` CRD support (see https://docs.nginx.com/nginx-ingress-controller/configuration/virtualserver-and-virtualserverroute-resources/)\n- Access to F5/NGINX downloads to fetch NGINX Instance Manager 2.4.0+ installation .deb file (when running in manual mode)\n- Valid NGINX license certificate and key to fetch NGINX Instance Manager packages (when running in automated mode)\n- Linux host running Docker to build the image\n\n## How to build\n\nThe install script can be used to build the Docker image using automated or manual install:\n\n```\n$ ./scripts/buildNIM.sh\nNGINX Instance Manager Docker image builder\n\n This tool builds a Docker image to run NGINX Instance Manager\n\n === Usage:\n\n ./scripts/buildNIM.sh [options]\n\n === Options:\n\n -h                     - This help\n -t [target image]      - Docker image name to be created\n -s                     - Enable Second Sight (https://github.com/F5Networks/SecondSight/) - optional\n\n Manual build:\n\n -n [filename]          - NGINX Instance Manager .deb package filename\n -w [filename]          - Security Monitoring .deb package filename - optional\n -p [filename]          - WAF policy compiler .deb package filename - optional\n\n Automated build:\n\n -i                     - Automated build - requires cert \u0026 key\n -C [file.crt]          - Certificate file to pull packages from the official NGINX repository\n -K [file.key]          - Key file to pull packages from the official NGINX repository\n -W                     - Enable Security Monitoring - optional\n -P [version]           - Enable WAF policy compiler, version can be any [v3.1088.2|v4.100.1|v4.2.0|v4.218.0|v4.279.0|v4.402.0|v4.457.0|v4.583.0] - optional\n\n === Examples:\n\n Manual build:\n        ./scripts/buildNIM.sh -n nim-files/nms-instance-manager_2.6.0-698150575~focal_amd64.deb \\\n                -w nim-files/nms-sm_1.0.0-697204659~focal_amd64.deb \\\n                -p nim-files/nms-nap-compiler-v4.2.0.deb \\\n                -t my.registry.tld/nginx-nms:2.6.0\n\n Automated build:\n        ./scripts/buildNIM.sh -i -C nginx-repo.crt -K nginx-repo.key\n                -W -P v4.583.0 -t my.registry.tld/nginx-nms:latest\n```\n\n### Automated build\n\n1. Clone this repo\n2. Get your license certificate and key to fetch NGINX Instance Manager packages from NGINX repository\n3. Build NGINX Instance Manager Docker image using:\n\nNGINX Instance Manager\n\n```\n./scripts/buildNIM.sh -t YOUR_DOCKER_REGISTRY/nginx-nim2:automated -i -C certs/nginx-repo.crt -K certs/nginx-repo.key\n```\n\nNGINX Instance Manager, Security Monitoring and WAF Policy Compiler\n\n```\n./scripts/buildNIM.sh -t YOUR_DOCKER_REGISTRY/nginx-nim2:automated -i -C certs/nginx-repo.crt -K certs/nginx-repo.key -W -P v4.457.0\n```\n\n### Manual build\n\n1. Clone this repository\n2. Download NGINX Instance Manager 2.4.0+ .deb installation file for Ubuntu 20.04 and copy it into `nim-files/`\n3. Optional: download Security Monitoring .deb installation file for Ubuntu 20.04 and copy it into `nim-files/`\n4. Optional: download WAF Policy Compiler .deb installation file for Ubuntu 20.04 and copy it into `nim-files/`\n5. Build NGINX Instance Manager Docker image using the provided script\n\nExample:\n\n```\ncd nim-files\n\napt-cache madison nms-instance-manager\napt-get download nms-instance-manager=2.15.1-1175574316~focal\n\napt-cache madison nms-sm\napt-get download nms-sm=1.7.1-1046510610~focal\n\napt-cache search nms-nap-compiler\napt-get download nms-nap-compiler-v4.815.0\n\ncd ..\n\n./scripts/buildNIM.sh \\\n        -t my-private-registry/nginx-instance-manager:2.15.1-nap-v4.815.0-manualbuild \\\n        -n nim-files/nms-instance-manager_2.15.1-1175574316~focal_amd64.deb \\\n        -w nim-files/nms-sm_1.7.1-1046510610~focal_amd64.deb \\\n        -p nim-files/nms-nap-compiler-v4.815.0_4.815.0-1~focal_amd64.deb\n```\n\n### Configuring and running\n\n1. Edit `manifests/1.nginx-nim.yaml` and specify the correct image by modifying the \"image\" line and configure NGINX Instance Manager username, password and the base64-encoded license file for automated license activation.\n\n```\nimage: your.registry.tld/nginx-nim2:tag\n[...]\nenv:\n  ### NGINX Instance Manager environment\n  - name: NIM_USERNAME\n    value: admin\n  - name: NIM_PASSWORD\n    value: nimadmin\n  - name: NIM_LICENSE\n    value: \"\u003cBASE64_ENCODED_LICENSE_FILE\u003e\"\n```\n\nTo base64-encode the license file the following command can be used:\n\n```\nbase64 -w0 NIM_LICENSE_FILENAME.lic\n```\n\nAdditionally, parameters user by NGINX Instance Manager to connect to ClickHouse can be configured:\n\n```\nenv:\n  [...]\n  - name: NIM_CLICKHOUSE_ADDRESS\n    value: clickhouse\n  - name: NIM_CLICKHOUSE_PORT\n    value: \"9000\"\n  ### If username is not set to \"default\", the clickhouse-users ConfigMap in 0.clickhouse.yaml shall be updated accordingly\n  - name: NIM_CLICKHOUSE_USERNAME\n    value: \"default\"\n  ### If password is not set to \"NGINXr0cks\", the clickhouse-users ConfigMap in 0.clickhouse.yaml shall be updated accordingly\n  - name: NIM_CLICKHOUSE_PASSWORD\n    value: \"NGINXr0cks\"\n```\n\n2. If Second Sight was built in the image, configure the relevant environment variables. See the documentation at https://github.com/F5Networks/SecondSight/#on-kubernetesopenshift\n\n```\nenv:\n  ### Second Sight Push mode\n  - name: STATS_PUSH_ENABLE\n    #value: \"true\"\n    value: \"false\"\n  - name: STATS_PUSH_MODE\n    value: CUSTOM\n    #value: PUSHGATEWAY\n  - name: STATS_PUSH_URL\n    value: \"http://192.168.1.5/callHome\"\n    #value: \"http://pushgateway.nginx.ff.lan\"\n  ### Push interval in seconds\n  - name: STATS_PUSH_INTERVAL\n    value: \"10\"\n```\n\n3. Check / modify files in `/manifests/certs` to customize the TLS certificate and key used for TLS offload\n\n4. Start and stop using\n\n```\n./scripts/nimDockerStart.sh start\n./scripts/nimDockerStart.sh stop\n```\n\n5. After starting NGINX Instance Manager it will be accessible from outside the cluster at:\n\nNGINX Instance Manager GUI: `https://nim2.f5.ff.lan`\nNGINX Instance Manager gRPC port: `nim2.f5.ff.lan:30443`\n\nand from inside the cluster at:\n\nNGINX Instance Manager GUI: `https://nginx-nim2.nginx-nim2`\nNGINX Instance Manager gRPC port: `nginx-nim2.nginx-nim2:443`\n\n\nSecond Sight REST API (if enabled at build time - see the documentation at `https://github.com/F5Networks/SecondSight`):\n- `https://nim2.f5.ff.lan/f5tt/instances`\n- `https://nim2.f5.ff.lan/f5tt/metrics`\n- Push mode (configured through env variables in `manifests/1.nginx-nim.yaml`)\n\nGrafana dashboard: `https://grafana.nim2.f5.ff.lan` - see [configuration details](contrib/grafana)\n\nRunning pods are:\n\n```\n$ kubectl get pods -n nginx-nim2 -o wide\nNAME                          READY   STATUS    RESTARTS   AGE    IP            NODE       NOMINATED NODE   READINESS GATES\nclickhouse-7bc96d6d56-jthtf   1/1     Running   0          5m8s   10.244.1.65   f5-node1   \u003cnone\u003e           \u003cnone\u003e\ngrafana-6f58d455c7-8lk64      1/1     Running   0          5m8s   10.244.2.80   f5-node2   \u003cnone\u003e           \u003cnone\u003e\nnginx-nim2-679987c54d-7rl6b   1/1     Running   0          5m8s   10.244.1.64   f5-node1   \u003cnone\u003e           \u003cnone\u003e\n```\n\n6. For NGINX Instances running on VM/bare metal only: after installing the nginx-agent on NGINX Instances to be managed with NGINX Instance Manager 2, update the file `/etc/nginx-agent/nginx-agent.conf` and modify the line:\n\n```\ngrpcPort: 443\n```\n\ninto:\n\n```\ngrpcPort: 30443\n```\n\nand then restart nginx-agent\n\n\n## Additional tools\n\n- [Grafana dashboard for telemetry](contrib/grafana)\n- [Docker compose](contrib/docker-compose)\n\n\n# Starting NGINX Instance Manager\n\n## On Kubernetes\n\n```\n$ ./scripts/nimDockerStart.sh start\nnamespace/nginx-nim2 created\nGenerating a RSA private key\n...................+++++\n...............................+++++\nwriting new private key to 'nim2.f5.ff.lan.key'\n-----\nsecret/nim2.f5.ff.lan created\ndeployment.apps/nginx-nim2 created\nservice/nginx-nim2 created\nservice/nginx-nim2-grpc created \nvirtualserver.k8s.nginx.org/vs-nim2 created\n\n$ kubectl get pods -n nginx-nim2 -o wide\nNAME                          READY   STATUS    RESTARTS   AGE    IP            NODE       NOMINATED NODE   READINESS GATES\nclickhouse-7bc96d6d56-jthtf   1/1     Running   0          5m8s   10.244.1.65   f5-node1   \u003cnone\u003e           \u003cnone\u003e\ngrafana-6f58d455c7-8lk64      1/1     Running   0          5m8s   10.244.2.80   f5-node2   \u003cnone\u003e           \u003cnone\u003e\nnginx-nim2-679987c54d-7rl6b   1/1     Running   0          5m8s   10.244.1.64   f5-node1   \u003cnone\u003e           \u003cnone\u003e\n```\n\nNGINX Instance Manager GUI is now reachable from outside the cluster at:\n- Web GUI: `https://nim2.f5.ff.lan`\n- gRPC: `nim2.f5.ff.lan:30443`\n- Second Sight: see [usage](https://github.com/F5Networks/SecondSight/blob/main/USAGE.md)\n\n## On docker-compose\n\nSee [docker-compose](contrib/docker-compose)\n\n# Stopping NGINX Instance Manager\n\n## On Kubernetes\n\n```\n$ ./scripts/nimDockerStart.sh stop\nnamespace \"nginx-nim2\" deleted\n```\n\n## On docker-compose\n\nSee [docker-compose](contrib/docker-compose)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabriziofiorucci%2Fnginx-nim-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabriziofiorucci%2Fnginx-nim-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabriziofiorucci%2Fnginx-nim-docker/lists"}