# NGINX + Let's Encrypt

> NGINX web server with automatic SSL certificate generation and renewal using Certbot.

- Category: Web Servers & Reverse Proxies
- Difficulty: intermediate
- Components: nginx, certbot
- Tags: nginx, ssl, https, certbot, letsencrypt
- Source: https://docker.recipes/web-servers/nginx-letsencrypt

## Overview

NGINX is a high-performance HTTP server, reverse proxy, and load balancer originally developed by Igor Sysoev in 2004 to solve the C10K problem of handling 10,000 concurrent connections. Built on an event-driven, asynchronous architecture, NGINX excels at serving static content, handling SSL/TLS termination, and managing high-traffic loads with minimal resource consumption compared to traditional process-based web servers. This stack combines NGINX with Certbot, the Electronic Frontier Foundation's ACME client for Let's Encrypt, creating an automated SSL certificate management solution. The two containers work in tandem where NGINX serves web traffic and handles HTTPS termination, while Certbot runs continuously to obtain initial certificates via HTTP-01 challenge validation and automatically renews them every 12 hours. This configuration eliminates the manual overhead of SSL certificate management while providing enterprise-grade web serving capabilities. This stack is ideal for system administrators running production websites, developers deploying applications that require HTTPS, and organizations needing cost-effective SSL certificates with zero-downtime renewals. The combination provides immediate HTTPS capability for any domain while maintaining NGINX's superior performance characteristics for high-traffic scenarios.

## Features

- Event-driven asynchronous architecture handling thousands of concurrent connections with minimal memory overhead
- Automatic SSL certificate issuance and renewal through Let's Encrypt ACME protocol integration
- HTTP/2 and HTTP/3 support for improved page load performance and multiplexed connections
- Built-in rate limiting and connection limiting to prevent abuse and DDoS attacks
- Zero-downtime certificate renewals with continuous Certbot monitoring every 12 hours
- WebSocket proxying support for real-time applications and bidirectional communication
- Advanced load balancing algorithms including round-robin, least-connections, and IP hash methods
- SSL/TLS termination with modern cipher suite support and security headers configuration

## Use cases

- Production websites requiring HTTPS with automated certificate management and high availability
- E-commerce platforms needing SSL encryption for payment processing and customer data protection
- API endpoints serving mobile applications or third-party integrations requiring secure HTTPS communication
- Blog and content management systems with high traffic volumes and strict uptime requirements
- Development and staging environments that mirror production HTTPS configurations for testing
- Small business websites transitioning from HTTP to HTTPS for SEO benefits and browser security warnings
- Multi-domain hosting environments where each site needs individual SSL certificates with automated renewal

## Prerequisites

- Domain name with DNS A record pointing to your server's public IP address for certificate validation
- Server with minimum 256MB RAM for NGINX plus additional 128MB for Certbot operations
- Open ports 80 and 443 on firewall for HTTP challenge validation and HTTPS traffic
- Basic understanding of NGINX server block configuration and SSL certificate concepts
- Docker and Docker Compose installed with sufficient disk space for certificate storage (approximately 100MB per domain)

## docker-compose.yml

```yaml
services:
  nginx:
    image: nginx:alpine
    container_name: nginx
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./certbot/conf:/etc/letsencrypt:ro
      - ./certbot/www:/var/www/certbot:ro
    networks:
      - web

  certbot:
    image: certbot/certbot
    container_name: certbot
    volumes:
      - ./certbot/conf:/etc/letsencrypt
      - ./certbot/www:/var/www/certbot
    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"
    networks:
      - web

networks:
  web:
    driver: bridge
```

## .env

```bash
# Domain Configuration
DOMAIN=example.com
EMAIL=admin@example.com
```

## Usage notes

- Docs: https://nginx.org/en/docs/ and https://certbot.eff.org/docs/
- Create nginx/conf.d/default.conf with server blocks before starting
- Initial cert: docker compose run --rm certbot certonly --webroot -w /var/www/certbot -d yourdomain.com
- Certbot auto-renews every 12 hours - nginx reloads needed for new certs
- Add location /.well-known/acme-challenge/ { root /var/www/certbot; } for validation
- Test config: docker exec nginx nginx -t

## Troubleshooting

- Certificate validation failed: Ensure domain DNS points to server IP and port 80 is accessible for HTTP-01 challenge
- NGINX fails to start with SSL errors: Run initial certificate generation before enabling HTTPS server blocks in configuration
- Browser shows certificate warnings: Check that NGINX is loading certificates from correct /etc/letsencrypt/live/ directory path
- Certbot renewal fails with rate limiting: Let's Encrypt allows 50 certificates per registered domain per week, wait or use staging environment
- NGINX configuration test fails: Run 'docker exec nginx nginx -t' to validate syntax before restarting containers
- Mixed content warnings in browser: Update application URLs to use HTTPS and enable HSTS headers in NGINX configuration

