Automate Docker Nginx SSL with Acme-Companion: A Step‑by‑Step Guide

Overview

Docker and Nginx are the de‑facto stack for deploying web applications, but managing SSL certificates manually is tedious. The Acme‑Companion project provides a lightweight companion container for nginx‑proxy that uses the ACME protocol (primarily Let’s Encrypt) to automatically issue, renew, and apply SSL certificates, enabling secure proxying for Docker containers.

Process

Core Value

Acme‑Companion was created to extend nginx‑proxy, which dynamically generates Nginx configuration from container environment variables but does not handle SSL. Acme‑Companion listens to Docker events, automatically requests certificates for newly started containers, and seamlessly integrates them into the Nginx configuration.

Why choose it? Simple, safe, efficient:

Full automation : From certificate request to Nginx reload, everything is handled without manual intervention.

Strong compatibility : Works with all Docker versions and is suitable for production.

Open source & free : Licensed under Apache 2.0 and maintained by the community with tens of thousands of stars.

In cloud‑native architectures, Acme‑Companion fits multi‑container scenarios such as microservice deployments or static site hosting, making Let’s Encrypt certificates truly plug‑and‑play and lowering operational overhead.

Feature Highlights

Automatic certificate management : Uses the acme.sh client, supports Let’s Encrypt or other ACME CAs, defaults to HTTP‑01 validation with optional DNS‑01.

Multi‑domain & wildcard support : Easily generate SAN or wildcard certificates (e.g., *.example.com) to cover subdomains.

Nginx hot reload : After certificate issuance, Nginx configuration is updated and reloaded automatically, no service restart required.

Strong encryption : Generates RFC7919‑compliant Diffie‑Hellman groups at startup to enhance TLS security.

Flexible challenge verification : HTTP‑01 needs public ports 80/443; DNS‑01 uses DNS TXT records, suitable for strict firewall environments.

Additional features include custom email notifications for renewals and IPv6 compatibility.

Installation Guide

Prerequisite: Docker must be running. The installation uses shared volumes for inter‑container communication.

Step 1: Start nginx‑proxy

docker run --detach \
    --name nginx-proxy \
    --publish 80:80 \
    --publish 443:443 \
    --volume certs:/etc/nginx/certs \
    --volume html:/usr/share/nginx/html \
    --volume /var/run/docker.sock:/tmp/docker.sock:ro \
    nginxproxy/nginx-proxy

The host Docker socket ( /var/run/docker.sock) is bound to /tmp/docker.sock inside the container, which nginx‑proxy requires.

Step 2: Start Acme‑Companion

docker run --detach \
    --name nginx-proxy-acme \
    --volumes-from nginx-proxy \
    --volume /var/run/docker.sock:/var/run/docker.sock:ro \
    --volume acme:/etc/acme.sh \
    --env "[email protected]" \
    nginxproxy/acme-companion

The Docker socket must also be bound inside this container. The DEFAULT_EMAIL variable provides a default contact address for Let’s Encrypt notifications.

Step 3: Configure Proxy Containers

For each service to be proxied, set the environment variables VIRTUAL_HOST (proxy domain) and LETSENCRYPT_HOST (certificate domain). Certificates are issued only for publicly reachable domains.

Example – proxy a simple Nginx container:

docker run --detach \
    --name my-app \
    --env "VIRTUAL_HOST=sub.tinywan.com" \
    --env "LETSENCRYPT_HOST=sub.tinywan.com" \
    nginx

If the application listens on a non‑standard port (e.g., Grafana on 3000), add VIRTUAL_PORT:

docker run --detach \
    --name grafana \
    --env "VIRTUAL_HOST=grafana.example.com" \
    --env "VIRTUAL_PORT=3000" \
    --env "LETSENCRYPT_HOST=grafana.example.com" \
    --env "[email protected]" \
    grafana/grafana

After starting the containers, accessing the domain will show HTTPS enabled. Certificates are valid for 90 days and Acme‑Companion will renew them automatically.