🧭 nginx-proxy

Automatic virtual host reverse proxy for Docker with Let's Encrypt

Overview • Prerequisites • Quick start • DNS setup • Use with your apps • Docker run example • Included services

Overview

Simple setup for jwilder/nginx-proxy with Let's Encrypt companion. It automatically routes requests based on hostnames and can provision certificates via ACME.

Prerequisites

• Docker and Docker Compose
• An external Docker network named web that your apps join:

docker network create web

Quick start

Bring up the proxy and ACME companion:

docker compose up -d

This stack exposes ports 80 and 443 and listens for containers on the web network.

Using with your app containers

Attach your containers to the same web network and set the environment variables below.

DNS setup

To route any subdomain of example.com through this proxy, create a wildcard DNS record pointing to this server's public IP.

• Create an A (or AAAA) record for *.example.com to your server's IP address.
• Optional: also point example.com to the same IP if you want the apex domain served.

Notes:

• A wildcard DNS record does not automatically create a wildcard TLS certificate. Certificates are issued per hostname unless you configure DNS-01 with a supported DNS provider.
• If you don't want a wildcard, you can instead create individual A/AAAA records (e.g., app1.example.com, app2.example.com).

Required/optional environment variables

• VIRTUAL_HOST: Comma-separated hostnames to route to this container (e.g., app.example.com).
• LETSENCRYPT_HOST: Hostname(s) for which to request TLS certificates. Typically the same as VIRTUAL_HOST.
• LETSENCRYPT_EMAIL (optional): Email used for ACME registration and renewal notices.
• HOST_PORT (optional): Port your app listens on inside the container. If omitted, the proxy detects the port automatically from EXPOSE or ports.

Example service

services:
  whoami:
    image: traefik/whoami
    container_name: whoami
    restart: always
    expose:
      - "80"          # alternatively, publish and set HOST_PORT
    environment:
      - VIRTUAL_HOST=example.com
      - LETSENCRYPT_HOST=example.com
      - LETSENCRYPT_EMAIL=you@example.com   # optional
      # - HOST_PORT=80                      # optional; auto-detected if omitted
    networks:
      - web

networks:
  web:
    external: true

Notes:

• Use expose to make the internal port visible to the proxy without publishing it on the host. If you instead publish with ports, HOST_PORT is typically unnecessary because the proxy will detect the exposed/published port.
• Ensure your DNS records point to the server running this proxy.

Docker run example (your app container)

If you prefer docker run, here's an example using all supported env variables for an app container (not the proxy):

# Create the external network once
docker network create web

# Run your application container
docker run -d \
  --name whoami \
  --restart always \
  --expose 80 \
  -e VIRTUAL_HOST=example.com \
  -e LETSENCRYPT_HOST=example.com \
  -e LETSENCRYPT_EMAIL=you@example.com \  # optional
  -e HOST_PORT=80 \                         # optional; auto-detected if omitted
  --network web \
  traefik/whoami

Notes:

• Replace example.com and the email with your domain and contact.

Included compose services

This repository's docker-compose.yml defines:

• nginx-proxy (listens on 80/443)
• nginx-proxy-acme companion (obtains and renews certificates)

Both services join the external web network.