Skip to content

Latest commit

 

History

History
191 lines (135 loc) · 4.78 KB

README.md

File metadata and controls

191 lines (135 loc) · 4.78 KB

Nginx Proxy

A custom nginx-proxy image based on jwilder/nginx-proxy with additional features for WordPress and EasyEngine environments.

Features

  • Automatic reverse proxy configuration via Docker container labels
  • SSL/TLS support with automatic certificate detection
  • HTTP Basic Authentication support
  • Wildcard HTTP Auth for WordPress Multisite
  • Custom vhost configurations
  • Access Control Lists (ACL)

HTTP Basic Authentication

Standard Authentication

Create htpasswd files in /etc/nginx/htpasswd/ to enable HTTP auth:

# For a specific domain
htpasswd -c /etc/nginx/htpasswd/example.com username

# Default auth for all sites without specific htpasswd
htpasswd -c /etc/nginx/htpasswd/default username

Wildcard Authentication (WordPress Multisite)

For WordPress multisite with subdomain configuration, you can use a single htpasswd file to protect both the main domain and all subdomains.

Naming Convention

Use the _wildcard. prefix:

/etc/nginx/htpasswd/_wildcard.domain.com

This file will apply HTTP auth to:

  • domain.com (main domain)
  • *.domain.com (all subdomains like blog.domain.com, shop.domain.com, etc.)

Lookup Order

The template checks for htpasswd files in this order:

  1. Exact match: /etc/nginx/htpasswd/blog.domain.com
  2. Wildcard (3 parts): /etc/nginx/htpasswd/_wildcard.domain.co.in (for 4+ part domains only)
  3. Wildcard (2 parts): /etc/nginx/htpasswd/_wildcard.example.com (for 2-3 part domains, or fallback)
  4. Default: /etc/nginx/htpasswd/default

Example Setup

# Create wildcard htpasswd for WordPress multisite
htpasswd -c /etc/nginx/htpasswd/_wildcard.example.com admin

# This protects: example.com, blog.example.com, shop.example.com, etc.

# Optional: Override for a specific subdomain
htpasswd -c /etc/nginx/htpasswd/api.example.com api_user

Multi-level TLDs

Multi-level TLDs (e.g., .co.in, .com.au) are fully supported:

Host Wildcard File Checked
blog.domain.co.in (4 parts) _wildcard.domain.co.in first, then _wildcard.co.in
domain.co.in (3 parts) _wildcard.co.in
blog.example.com (3 parts) _wildcard.example.com
example.com (2 parts) _wildcard.example.com 
# For domain.co.in multisite (multi-level TLD)
htpasswd -c /etc/nginx/htpasswd/_wildcard.domain.co.in admin

# This will protect:
# - domain.co.in
# - blog.domain.co.in
# - shop.domain.co.in
# - etc.

Access Control Lists (ACL)

Create ACL files to restrict access by IP:

# Per-domain ACL
/etc/nginx/vhost.d/example.com_acl

# Default ACL for all sites
/etc/nginx/vhost.d/default_acl

Example ACL content:

allow 192.168.1.0/24;
allow 10.0.0.0/8;
deny all;

Custom Vhost Configuration

Per-domain configuration

# Main vhost config
/etc/nginx/vhost.d/example.com

# Location-specific config
/etc/nginx/vhost.d/example.com_location

Default configuration

/etc/nginx/vhost.d/default
/etc/nginx/vhost.d/default_location

SSL Certificate Handling

Certificate Lookup

The proxy automatically detects SSL certificates from /etc/nginx/certs/:

/etc/nginx/certs/example.com.crt
/etc/nginx/certs/example.com.key

Fallback Certificate Behavior

When a vhost is accessed via HTTPS but no matching certificate is found:

  1. If default certificate exists: Uses /etc/nginx/certs/default.crt and returns 503
  2. If no default certificate: Rejects the SSL/TLS handshake

This prevents certificate warning dialogs in browsers and improves security by not exposing invalid certificates.

Environment Variables

Variable Description Default
VIRTUAL_HOST Comma-separated list of domains -
VIRTUAL_PORT Port to proxy to 80
VIRTUAL_PROTO Protocol (http, https, uwsgi, fastcgi) http
HTTPS_METHOD redirect, noredirect, nohttps redirect
SSL_POLICY SSL/TLS policy Mozilla-Modern
SSL_STAPLING Enable OCSP stapling (on or off) on
HSTS HSTS header value max-age=31536000
CERT_NAME Custom certificate name auto-detected
NETWORK_ACCESS external or internal external

Docker Compose Example

services:
  nginx-proxy:
    image: your-nginx-proxy-image
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - ./certs:/etc/nginx/certs:ro
      - ./htpasswd:/etc/nginx/htpasswd:ro
      - ./vhost.d:/etc/nginx/vhost.d:ro

  wordpress-multisite:
    image: wordpress
    environment:
      - VIRTUAL_HOST=example.com,*.example.com
    # HTTP auth via /etc/nginx/htpasswd/_wildcard.example.com