Nic Docker Images

NIC Docker Image Build System

Dockerfile Architecture

Single build/Dockerfile (~850 lines), heavily multi-stage. The BUILD_OS arg selects which base image stage is used.

nginx-files (scratch)           <- Collects repo files, signing keys, scripts
  |
OS-specific base stages         <- One per variant (debian, alpine, ubi, *-plus, *-nap)
  |
FROM ${BUILD_OS} AS common      <- Runs common.sh + patch-os.sh, sets permissions
  |
TARGET stages (final image)     <- local, container, goreleaser, debug, download, aws, patched

Image Variants

3 OS families x 2 NGINX editions x optional NAP = ~20 variants.

Architecture: amd64 + arm64 for OSS and Plus. NAP variants are amd64 only.

Makefile Image Targets

All targets call docker build --platform linux/$(ARCH) --target $(TARGET) -f build/Dockerfile.

Plus images receive $(PLUS_ARGS): --secret id=nginx-repo.crt --secret id=nginx-repo.key.

TARGET Variable

Key Build Args

Build Scripts (build/scripts/)

Key Conventions

• All images run as UID 101 (nginx user), with setcap cap_net_bind_service for ports 80/443
• Docker BuildKit always enabled: uses --mount=type=bind, --mount=type=secret, --mount=type=cache
• Plus credentials use --secret mounts, never COPY into layers
• Fixed upstream base images use pinned @sha256: digests for reproducibility; some stages intentionally use build-arg/tag-selected bases (for example BUILD_OS or download/prebuilt images)
• All images include nginx-module-otel (OpenTelemetry) and nginx-agent (usage reporting)
• Plus images add njs and fips-check modules
• Renovate manages base image digests and tool versions via # renovate: comments

Gotchas

• Never store Plus credentials in image layers -- always use --secret mounts
• Never add arm64 to NAP image matrices -- NAP is amd64 only
• Always use BUILD_OS to select variants, not separate Dockerfiles
• The common stage unifies all variants -- changes there affect every image
• common.sh detects Plus via BUILD_OS containing "plus" and creates OIDC directories
• patch-os.sh handles OS-level security updates at build time
• When adding new image dependencies, update the relevant OS-specific stage AND the common stage if needed

Source: nginx/kubernetes-ingress — distributed by TomeVault.