🚀 Distroless FreeNGINX: Hardened & Optimized image

Production-ready, security-focused FreeNGINX image with HTTP/3, QUIC, ECH and PQC support.

Important

The QuicTLS is now deprecated. I use OpenSSL, since this library natively supports OCSP, PQC, ECH and QUIC⚠️

Important

NJS module has been removed due to security vulnerabilities in libxml2/libxslt dependencies⚠️

Tip

You can find an example configuration file in the repository for successfully configuring HTTP/3, ECH and PQC💡

Important

UID/GID changed to 10001 - it's recommended for Kubernetes and prevents conflicts with system users⚠️

🌐 Image Variants

Docker Hub:

ammnt/freenginx

GitHub Container Registry:

ghcr.io/ammnt/freenginx

📦 Quick Start

Docker Run

docker run -d \
--name freenginx \
-p 80:8080 \
-p 443:8443 \
ammnt/freenginx

🔧 Advanced Configuration

🎯 Recommended to use in Rootless mode:

https://docs.docker.com/engine/security/rootless/

Docker Compose (Recommended)

services:
freenginx:
image: ammnt/freenginx:latestuser: "10001:10001"read_only: trueprivileged: falsetmpfs:
- /tmp:mode=1700,size=1G,noexec,nosuid,nodev,uid=10001,gid=10001cap_drop:
- allcontainer_name: freenginxsecurity_opt:
- no-new-privileges=true
- apparmor=docker-freenginx
- seccomp=./freenginx-seccomp.jsonvolumes:
- "./conf:/etc/freenginx:ro"
...

Example Deployment (PSS Restricted Level Compliant)

apiVersion: v1kind: Deploymentmetadata:
name: freenginx-pss-restrictedspec:
containers:
- name: freenginximage: ammnt/freenginx:latestsecurityContext:
capabilities:
drop:
- ALLprivileged: falserunAsUser: 10001runAsGroup: 10001seccompProfile:
type: RuntimeDefaultrunAsNonRoot: truereadOnlyRootFilesystem: trueallowPrivilegeEscalation: false
...

Repository structure

freenginx/
├── 🔧 AGENTS.md # Dedicated file that guides AI coding agents
├── 📜 CODE_OF_CONDUCT.md # Code of Conduct for contributors
├── 🤝 CONTRIBUTING.md # Contributing guidelines
├── 🔑 cosign.pub # Public key for image signing (Sigstore/cosign)
├── ⚙️ default.conf # Default FreeNGINX configuration
├── 🐳 dive-ci.yml # Dive configuration for Docker image analysis
├── 🐳 Dockerfile.template # Dockerfile template (dynamic generation)
├── 🙈 .dockerignore # Files to exclude from Docker build context
├── ⚙️ .editorconfig # EditorConfig for consistent coding styles
├── 🔧 .env # Environment variables configuration
├── 📄 example.conf # Example FreeNGINX configuration for HTTP/3
├── 🚀 freenginx.conf # Main FreeNGINX configuration file
├── 🛡️ freenginx-seccomp.json # Seccomp profile for FreeNGINX security
├── 📦 freenginx.toml # Additional FreeNGINX configuration (TOML format)
├── ⚙️ .gitattributes # Git attributes configuration
├── 📁 .github/ # GitHub-specific configuration
│ ├── 📋 dependabot.yml # Automated dependency updates
│ ├── 📁 ISSUE_TEMPLATE/ # Issue creation templates
│ │ ├── 🐛 bug_report.md # Bug report template
│ │ ├── ⚙️ config.yml # Issue templates configuration
│ │ └── 💡 feature_request.md # Feature request template
│ ├── 🏷️ labeler.yml # PR labeler configuration
│ ├── 📝 PULL_REQUEST_TEMPLATE.md # Pull Request template
│ └── 📁 workflows/ # GitHub Actions CI/CD pipelines
│ ├── 🔨 build.yml # Build and testing workflow
│ ├── 🔒 codeql.yml # Static security analysis (CodeQL)
│ └── 🏷️ label.yml # Workflow for triage PR and apply labels
├── 🙈 .gitignore # Git ignore rules
├── ✅ hadolint.yaml # Hadolint configuration (Dockerfile linter)
├── ⚖️ LICENSE # License agreement
├── 📖 README.md # Main project documentation
├── 🔒 SECURITY.md # Security policy and vulnerability reporting
└── 🔍 trivy.yaml # Trivy configuration (vulnerability scanning)

🔥 Why Choose This Image?

Compiler Options Hardening Guide (OpenSSF Best Practices) providing comprehensive security:

• Memory protection - stack smashing protection (-fstack-protector-strong), stack clash protection (-fstack-clash-protection)
• Control Flow Integrity - full CFI protection against ROP/JOP attacks via Intel CET (-fcf-protection=full)
• Initialization hardening - automatic variable initialization to prevent data leaks (-ftrivial-auto-var-init=pattern)
• Binary hardening - position independent executable (-static-pie) for full ASLR (PaX, Linux kernel)
• Runtime protections - FORTIFY_SOURCE level 3 for buffer overflow detection (-D_FORTIFY_SOURCE=3)
• C++ assertions - enhanced standard library security checks (-D_GLIBCXX_ASSERTIONS)
• Linker hardening - read-only relocations and immediate binding (-Wl,-z,relro,-z,now), no-exec stack (-Wl,-z,noexecstack), separate code/data segments (-Wl,-z,separate-code), CET enforcement (-Wl,-z,shstk,-z,ibt)
• Compiler warnings - comprehensive warning set with errors for critical issues (-Wall -Wextra -Wformat=2 -Wimplicit-fallthrough -Werror=format-security -Werror=return-type)

Runtime Security

• Rootless by design - unprivileged runtime user (Docker Bench Security, OCI Runtime Specification)
• Distroless base - built from scratch with zero bloat (SLSA Level 3 requirements)
• Minimal attack surface - no shell, no package manager, and no unnecessary modules (CIS Docker Benchmark, Principle of Least Privilege)
• Server header removal - anonymous signature ("security through obscurity")
• Kubernetes PSS compliant - fully conforms to Pod Security Standards (baseline & restricted)
• Docker security standards - follows CIS Docker Benchmarks and best practices
• Native QUIC and HTTP/3 support - OpenSSL and QUIC without patches or experimental implementations (RFC 9114, RFC 9000)
• Native PQC support - hybrid post-quantum key exchange algorithms in elliptic curves (NIST PQC Standardization, FIPS 203/204/205)
• Native TLS 1.3 with 0-RTT (RFC 8446, RFC 9001)
• Native support for the Encrypted Client Hello (ECH) - extension of the TLS 1.3 protocol (RFC 9849)

Supply Chain Integrity

• Signed images - signatures and provenance attestation (SLSA Level 3 requirements, in-toto attestations)
• Comprehensive scanning by security tools (Scout, Trivy, Snyk, Grype, Dockle, Hadolint, Clair, Checkov)
• SBOM generation with Syft (NTIA Software Component Transparency)

🚀 Ultimate Optimization

Size Optimization

• Multi-stage build with Alpine builder + scratch final image (Dockerfile best practices, BuildKit optimizations)
• Static compilation - static binary with minimal dependencies
• Mint tool integration - slimmed version of the image
• UPX runtime efficiency - minimal memory overhead with fast decompression (Executable compression)
• Binary stripping and LTO optimization (DWARF debugging standard)

Performance Features

• zlib-ng with modern compression algorithms (RFC 1950, RFC 1951, RFC 1952)
• PCRE2 with JIT compilation for regex performance
• Thread pool support for async I/O operations
• TCP Fast Open and SSL session resumption (RFC 7413, RFC 8446)
• Graceful shutdown - SIGQUIT handling for proper connection draining (RFC 7230)
• Brotli and ZSTD compression mechanisms support (RFC 7932, RFC 8878)
• Native TLS compression - support for certificate compression (RFC 8879)

Quality Metrics

• Image efficiency - perfect score in Dive analysis (100%)
• Comprehensive OCI labels - standardized metadata and annotations
• No excess ENTRYPOINT - no unnecessary wrapper scripts or bloat (12-factor app methodology, Cloud Native patterns)
• Built-in HEALTHCHECK - Configuration validation every 30s with 10s timeout (Docker HEALTHCHECK specification)

🤝 Contributing & Support

Found an issue or have an improvement?

• Open an Issue
• Feature Request

Note: This image is designed for security-conscious production environments. For development purposes, consider using the official FreeNGINX image with full debugging capabilities.

📄 License

This project is open source and maintained with ❤️ by ammnt.