https://github.com/ammnt/freenginx
Distroless FreeNGINX with HTTP/3, QUIC and PQC support🚀
https://github.com/ammnt/freenginx
0-rtt alpine distroless docker fastopen fork freenginx hardened http2 http3 https nginx openssl pqc quic rootless tls unprivileged web
Last synced: 3 days ago
JSON representation
Distroless FreeNGINX with HTTP/3, QUIC and PQC support🚀
- Host: GitHub
- URL: https://github.com/ammnt/freenginx
- Owner: ammnt
- License: bsd-2-clause
- Created: 2024-03-31T08:35:37.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-07T12:16:35.000Z (7 days ago)
- Last Synced: 2026-02-07T17:43:45.364Z (7 days ago)
- Topics: 0-rtt, alpine, distroless, docker, fastopen, fork, freenginx, hardened, http2, http3, https, nginx, openssl, pqc, quic, rootless, tls, unprivileged, web
- Language: Dockerfile
- Homepage: https://msftcnsi.com/
- Size: 589 KB
- Stars: 12
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# 🚀 Distroless FreeNGINX: Hardened & Optimized image
[](https://github.com/ammnt/freenginx/actions/workflows/build.yml)
[](https://github.com/ammnt/freenginx/stargazers)
[](https://github.com/ammnt/freenginx/issues)
> **Production-ready, security-focused FreeNGINX image with HTTP/3, QUIC and PQC support.**
> [!IMPORTANT]
> QuicTLS is now deprecated. I use OpenSSL, since this library natively supports OCSP, PQC and QUIC⚠️
> [!IMPORTANT]
> NJS module has been removed due to security vulnerabilities in libxml2/libxslt dependencies⚠️
> [!TIP]
> You can find an example [configuration file](example.conf) in the repository for successfully configuring HTTP/3 and PQC💡
> [!IMPORTANT]
> UID/GID changed to 10001 - it's [recommended](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/) for Kubernetes and prevents conflicts with system users⚠️
## 🌐 Image Variants
Docker Hub:
> **ammnt/freenginx:latest**
GitHub Container Registry:
> **ghcr.io/ammnt/freenginx:latest**
## 📦 Quick Start
### Docker Run
```bash
docker run -d \
--name freenginx \
-p 80:8080 \
-p 443:8443 \
ammnt/freenginx:latest
```
## 🔧 Advanced Configuration
## 🎯 Recommended to use in Rootless mode:
https://docs.docker.com/engine/security/rootless/
### Docker Compose (Recommended)
```yaml
services:
freenginx:
image: ammnt/freenginx:latest
user: "10001:10001"
read_only: true
privileged: false
tmpfs:
- /tmp:mode=1700,size=1G,noexec,nosuid,nodev,uid=10001,gid=10001
cap_drop:
- all
container_name: freenginx
security_opt:
- no-new-privileges=true
- apparmor=docker-freenginx
- seccomp=./freenginx-seccomp.json
volumes:
- "./conf:/etc/freenginx:ro"
...
```
### Example Deployment (PSS Restricted Level Compliant)
```yaml
apiVersion: v1
kind: Deployment
metadata:
name: freenginx-pss-restricted
spec:
containers:
- name: freenginx
image: ammnt/freenginx:latest
securityContext:
capabilities:
drop:
- ALL
privileged: false
runAsUser: 10001
runAsGroup: 10001
seccompProfile:
type: RuntimeDefault
runAsNonRoot: true
readOnlyRootFilesystem: true
allowPrivilegeEscalation: false
...
```
## 🔥 Why Choose This Image?
### **GCC hardened compilation suite (-fhardened) providing comprehensive security:**
- **Memory protection** - stack smashing protection, stack clash protection
- **Control Flow Integrity** - full CFI protection against ROP/JOP attacks (Intel CET)
- **Initialization hardening** - automatic zero-initialization to prevent data leaks
- **Binary hardening** - position idependent executables (PIE) for ASLR (PaX ASLR, Linux kernel ASLR)
- **Runtime protections** - FORTIFY_SOURCE level 3 for buffer overflow detection
- **C++ assertions** - enhanced standard library security checks
- **Linker hardening** - read-only relocations and immediate binding (ELF hardening, RELRO)
### **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)
### **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)
- **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 3s timeout (Docker HEALTHCHECK specification)
## 🤝 Contributing & Support
Found an issue or have an improvement?
- [Open an Issue](https://github.com/ammnt/freenginx/issues/new?template=bug_report.md)
- [Feature Request](https://github.com/ammnt/freenginx/issues/new?template=feature_request.md)
> **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](https://msftcnsi.com).