Reverse Proxy

Docker-based reverse proxy setup using nginx-proxy for automatic service discovery and routing. This setup allows you to run multiple services on a single server and route traffic based on domain names.

Overview

This project provides a centralized reverse proxy solution that:

• Automatically discovers and configures routing for Docker containers
• Handles HTTP and HTTPS traffic on ports 80 and 443
• Supports CORS for cross-origin requests
• Integrates with Cloudflare for SSL/TLS termination (default)
• Optionally supports Let's Encrypt for direct SSL certificate management

Architecture

The reverse proxy uses jwilder/nginx-proxy which automatically generates nginx configuration by monitoring Docker containers. When a container starts with VIRTUAL_HOST environment variable, the proxy automatically routes traffic to it.

Key Components:

• reverse-proxy: Main nginx-proxy container that handles routing
• acme-companion (optional): Let's Encrypt certificate management
• External network: reverse-proxy network for service communication

Prerequisites

• Docker and Docker Compose installed
• Ports 80 and 443 available on the host
• Domain names configured (DNS pointing to your server)

Quick Start

1. Create the external Docker network:

   docker network create reverse-proxy

2. Start the reverse proxy:

   docker compose up -d

3. Verify it's running:

   docker compose ps
   docker compose logs -f reverse-proxy

Adding Services

To proxy a service through this reverse proxy, configure it in a separate docker-compose file:

services:
  your-app:
    image: your-image:latest
    environment:
      - VIRTUAL_HOST=yourdomain.com
      - VIRTUAL_PORT=8080  # Only if app doesn't use port 80
    networks:
      - reverse-proxy

networks:
  reverse-proxy:
    external: true

The reverse proxy will automatically detect the new container and configure routing.

SSL/HTTPS Configuration

Using Cloudflare (Default)

By default, this setup is designed to work behind Cloudflare:

1. Configure your domain's DNS in Cloudflare to point to your server
2. Set SSL/TLS mode to "Full" or "Full (strict)" in Cloudflare dashboard
3. Cloudflare handles SSL termination and forwards traffic to the proxy

Using Let's Encrypt (Optional)

To use Let's Encrypt instead of Cloudflare:

1. Uncomment the acme-companion service in docker-compose.yml
2. Uncomment the ./nginx/certs volume mount in the reverse-proxy service
3. Update DEFAULT_EMAIL with your email address
4. Restart the reverse proxy: docker compose up -d
5. Add LETSENCRYPT_HOST environment variable to your services:

   environment:
     - VIRTUAL_HOST=yourdomain.com
     - LETSENCRYPT_HOST=yourdomain.com

Important: When using Let's Encrypt, your server must be directly accessible on ports 80 and 443 (not proxied through Cloudflare).

Certificate Storage: SSL certificates will be stored in nginx/certs/ and ACME challenge files in nginx/acme/. These directories are in .gitignore for security.

Directory Structure

reverse-proxy/
├── docker-compose.yml          # Main configuration
├── nginx/
│   ├── conf.d/
│   │   ├── 00-proxy.conf       # Global proxy settings
│   │   └── default-site.conf   # Default server configuration
│   ├── vhost.d/
│   │   └── default             # Security headers and CORS
│   ├── html/
│   │   └── index.html          # Custom default page
│   ├── certs/                  # SSL certificates (when using Let's Encrypt)
│   └── acme/                   # ACME challenge files (when using Let's Encrypt)
└── README.md

Configuration Files

docker-compose.yml

Main reverse proxy configuration with service definitions and network setup.

nginx/conf.d/00-proxy.conf

Global nginx proxy settings applied to all virtual hosts:

Security:

• Server tokens disabled (hides nginx version)
• Invalid headers ignored

Client Settings:

• Unlimited body size for large uploads
• 512KB body buffer size
• Optimized header buffers

Timeouts:

• Client timeouts: 20 seconds (body and headers)
• Proxy timeouts: 120 seconds (connect, send, read)
• Keepalive: 15 seconds

Performance:

• Gzip compression enabled for text, JSON, CSS, JavaScript, fonts, and SVG
• Compression level 6 (balanced between speed and size)
• Proxy buffering optimized with 8x4KB buffers

nginx/conf.d/default-site.conf

Default server configuration that serves a fallback page when no VIRTUAL_HOST matches the request. This prevents nginx error pages from being shown to end users.

nginx/vhost.d/default

Security headers and CORS configuration applied to all virtual hosts:

Security Headers:

• X-Frame-Options: SAMEORIGIN - Prevents clickjacking attacks
• X-Content-Type-Options: nosniff - Prevents MIME type sniffing
• X-XSS-Protection: 1; mode=block - Enables XSS filter
• Referrer-Policy: strict-origin-when-cross-origin - Controls referrer information
• HSTS available (commented by default, enable if using Let's Encrypt)

CORS Configuration:

• Allows cross-origin requests with credentials
• Supports all common HTTP methods (GET, POST, PUT, PATCH, DELETE, OPTIONS)
• Custom headers allowed including "Context"
• Preflight requests cached for 24 hours
• Origin-based access control

Additional Protection:

• Rate limiting: 10 requests/second per IP (burst of 20 allowed)
• Hidden files blocked (.env, .git, .htaccess, etc.)

nginx/html/index.html

Custom default page displayed when accessing the server without a configured service. Features:

• Professional, responsive design
• Clear instructions for configuration
• Neutral color scheme with gradient background
• Mobile-friendly layout

nginx/certs/ (when using Let's Encrypt)

Directory where SSL certificates are stored by acme-companion. This directory is ignored by git for security.

nginx/acme/ (when using Let's Encrypt)

Directory for ACME challenge files and acme.sh configuration. This directory is ignored by git.

Common Commands

# Start the reverse proxy
docker compose up -d

# Stop the reverse proxy
docker compose down

# View logs
docker compose logs -f reverse-proxy

# Restart after configuration changes
docker compose restart reverse-proxy

# Check status
docker compose ps

Troubleshooting

Seeing the default "Reverse Proxy Configured" page:

• This means the reverse proxy is working but no service is configured for this domain
• Verify the container has VIRTUAL_HOST environment variable set
• Confirm the container is connected to the reverse-proxy network
• Check that the domain in VIRTUAL_HOST matches the URL you're accessing

Service not accessible:

• Verify the container is connected to the reverse-proxy network
• Check that VIRTUAL_HOST is set correctly
• Review logs: docker compose logs reverse-proxy

SSL issues:

• If using Cloudflare, ensure SSL mode is "Full" or "Full (strict)"
• If using Let's Encrypt, verify ports 80/443 are publicly accessible
• Check that DNS is properly configured

Security Features

This reverse proxy includes multiple security layers:

DDoS Protection

• Rate limiting: 10 requests/second per IP with burst capacity of 20
• Automatic HTTP 429 response when limits are exceeded
• Connection limiting per IP address

Security Headers

Modern security headers are automatically applied to all responses to protect against common web vulnerabilities:

• Clickjacking protection: X-Frame-Options prevents your site from being embedded in iframes
• MIME sniffing prevention: X-Content-Type-Options prevents browsers from MIME-sniffing
• XSS protection: X-XSS-Protection enables browser XSS filters
• Referrer control: Strict referrer policy to protect user privacy

Access Control

• Hidden files (.env, .git, etc.) automatically blocked
• Invalid HTTP headers rejected
• Server version information hidden from responses

Performance Optimization

• Gzip compression reduces bandwidth by 60-80% for text content
• Optimized buffer sizes for handling large requests
• Efficient proxy buffering for backend communication
• Keepalive connections reduce latency

Customization

Adjusting Upload Limits

Edit nginx/conf.d/00-proxy.conf and modify:

client_max_body_size 100M;  # Change to your desired limit

Modifying Rate Limiting

Edit nginx/vhost.d/default to adjust rate limits:

limit_req zone=general burst=20 nodelay;  # Adjust burst value

Or edit nginx/conf.d/00-proxy.conf to change the base rate:

limit_req_zone $binary_remote_addr zone=general:10m rate=10r/s;  # Adjust rate

Enabling HSTS (for Let's Encrypt)

If using Let's Encrypt instead of Cloudflare, uncomment in nginx/vhost.d/default:

add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;

CORS Customization

To restrict CORS to specific origins instead of allowing all, edit nginx/vhost.d/default:

# Replace "$http_origin" with your specific domain
add_header 'Access-Control-Allow-Origin' "https://yourdomain.com" always;

License

This is a configuration repository for open-source components. The nginx-proxy and acme-companion images are subject to their respective licenses.