Convert Figma logo to code with AI

nginx-proxy logoacme-companion

Automated ACME SSL certificate generation for nginx-proxy

7,376
819
7,376
49

Top Related Projects

Automated nginx proxy for Docker containers using docker-gen

50,061

The Cloud Native Application Proxy

56,905

Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS

Docker container for managing Nginx proxy hosts with a simple, powerful interface

31,293

Certbot is EFF's tool to obtain certs from Let's Encrypt and (optionally) auto-enable HTTPS on your server. It can also act as a client for any other CA that uses the ACME protocol.

Quick Overview

ACME Companion is a Docker container designed to automate the creation, renewal, and use of Let's Encrypt certificates for proxied Docker containers. It works alongside the nginx-proxy container to provide HTTPS support with minimal configuration, making it easier to secure web applications running in Docker environments.

Pros

  • Automatic SSL/TLS certificate generation and renewal
  • Seamless integration with nginx-proxy
  • Supports multiple domains and subdomains
  • Easy to set up and use with Docker Compose

Cons

  • Limited to use with nginx-proxy
  • Requires understanding of Docker networking
  • May have performance overhead in large-scale deployments
  • Potential security risks if not properly configured

Getting Started

To use ACME Companion with nginx-proxy, follow these steps:

  1. Create a docker-compose.yml file with the following content:
version: '3'
services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - certs:/etc/nginx/certs
      - vhost:/etc/nginx/vhost.d
      - html:/usr/share/nginx/html

  acme-companion:
    image: nginxproxy/acme-companion
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - certs:/etc/nginx/certs
      - vhost:/etc/nginx/vhost.d
      - html:/usr/share/nginx/html
      - acme:/etc/acme.sh
    environment:
      - NGINX_PROXY_CONTAINER=nginx-proxy

volumes:
  certs:
  vhost:
  html:
  acme:
  1. Run the containers:
docker-compose up -d
  1. Add your web application container to the same Docker network and set the required environment variables:
  webapp:
    image: your-webapp-image
    environment:
      - VIRTUAL_HOST=example.com
      - LETSENCRYPT_HOST=example.com
      - LETSENCRYPT_EMAIL=your-email@example.com

ACME Companion will automatically generate and renew SSL/TLS certificates for your web application.

Competitor Comparisons

Automated nginx proxy for Docker containers using docker-gen

Pros of nginx-proxy

  • Simpler setup for basic reverse proxy needs
  • Lighter weight, as it doesn't include SSL/TLS certificate management
  • More flexible for custom configurations without SSL/TLS concerns

Cons of nginx-proxy

  • Lacks built-in SSL/TLS certificate management
  • Requires manual configuration for HTTPS support
  • May need additional tools or services for complete SSL/TLS automation

Code Comparison

nginx-proxy:

FROM nginx:alpine
COPY nginx.tmpl /etc/docker-gen/templates/
COPY docker-entrypoint.sh /app/docker-entrypoint.sh
ENTRYPOINT ["/app/docker-entrypoint.sh"]
CMD ["forego", "start", "-r"]

acme-companion:

FROM alpine:3.14
RUN apk add --no-cache bash curl openssl
COPY app/ /app/
ENTRYPOINT ["/app/entrypoint.sh"]

Key Differences

  1. Purpose: nginx-proxy focuses on reverse proxy functionality, while acme-companion specializes in SSL/TLS certificate management.
  2. Integration: acme-companion is designed to work alongside nginx-proxy, providing automated HTTPS support.
  3. Complexity: nginx-proxy is simpler for basic setups, while acme-companion adds complexity but offers automated SSL/TLS management.
  4. Use cases: nginx-proxy is suitable for environments where SSL/TLS is not required or managed separately, while acme-companion is ideal for automating HTTPS in Docker environments.
50,061

The Cloud Native Application Proxy

Pros of Traefik

  • Built-in service discovery and automatic configuration
  • Supports multiple providers (Docker, Kubernetes, etc.) out of the box
  • More feature-rich with advanced routing capabilities

Cons of Traefik

  • Steeper learning curve, especially for complex configurations
  • Can be resource-intensive for smaller deployments
  • Configuration syntax may be less intuitive for those familiar with Nginx

Code Comparison

ACME Companion (Nginx configuration):

server {
    listen 80;
    server_name example.com;
    location / {
        return 301 https://$host$request_uri;
    }
}

Traefik (YAML configuration):

http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      entrypoints:
        - web
      middlewares:
        - redirect-to-https

Both projects aim to simplify SSL/TLS certificate management and reverse proxy configuration. ACME Companion focuses on Nginx and Let's Encrypt integration, while Traefik offers a more comprehensive solution with built-in service discovery and support for multiple providers. Traefik's configuration is typically more concise and dynamic, but it may require more time to master. ACME Companion, being Nginx-based, might be more familiar to those already using Nginx in their infrastructure.

56,905

Fast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS

Pros of Caddy

  • Automatic HTTPS out of the box, simplifying SSL/TLS setup
  • More versatile as a standalone web server, not just a proxy
  • Simpler configuration with a human-readable format

Cons of Caddy

  • Potentially higher resource usage compared to Nginx
  • Less mature ecosystem and community support
  • May require more manual configuration for complex setups

Code Comparison

Caddy configuration example:

example.com {
  reverse_proxy localhost:8080
}

acme-companion (used with nginx-proxy) configuration:

version: '3'
services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    ports:
      - "80:80"
      - "443:443"
  acme-companion:
    image: nginxproxy/acme-companion
    volumes_from:
      - nginx-proxy

Caddy offers a more straightforward configuration for basic setups, while acme-companion requires additional Docker services but integrates well with existing Nginx setups. Caddy's built-in HTTPS automation simplifies SSL/TLS management, whereas acme-companion handles this separately for Nginx. The choice between the two depends on specific project requirements, existing infrastructure, and desired level of control over the web server configuration.

Docker container for managing Nginx proxy hosts with a simple, powerful interface

Pros of nginx-proxy-manager

  • User-friendly web interface for managing proxies and SSL certificates
  • Built-in support for Let's Encrypt certificate generation and renewal
  • Easy setup with Docker Compose, suitable for less technical users

Cons of nginx-proxy-manager

  • Less flexible for advanced configurations compared to acme-companion
  • May consume more resources due to additional components (e.g., web UI)
  • Not as tightly integrated with the Docker ecosystem as acme-companion

Code Comparison

acme-companion:

version: '2'
services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    ports:
      - "80:80"
      - "443:443"
  acme-companion:
    image: nginxproxy/acme-companion
    volumes_from:
      - nginx-proxy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - acme:/etc/acme.sh
volumes:
  acme:

nginx-proxy-manager:

version: '3'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    ports:
      - '80:80'
      - '81:81'
      - '443:443'
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt

The code comparison shows that nginx-proxy-manager has a simpler configuration, while acme-companion requires more setup but offers tighter integration with the nginx-proxy container.

31,293

Certbot is EFF's tool to obtain certs from Let's Encrypt and (optionally) auto-enable HTTPS on your server. It can also act as a client for any other CA that uses the ACME protocol.

Pros of Certbot

  • Widely adopted and well-established solution for SSL/TLS certificate management
  • Supports a broader range of web servers and platforms beyond Nginx
  • Offers more flexibility in certificate issuance and renewal processes

Cons of Certbot

  • Requires manual configuration and setup for each domain
  • May need additional scripting for automated renewals in complex environments
  • Less seamless integration with Nginx proxy setups compared to ACME Companion

Code Comparison

ACME Companion (Docker Compose):

services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
  acme-companion:
    image: nginxproxy/acme-companion
    volumes_from:
      - nginx-proxy
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - acme:/etc/acme.sh

Certbot (Shell):

certbot certonly --webroot -w /var/www/example -d example.com -d www.example.com

ACME Companion is designed for seamless integration with Nginx Proxy Manager in Docker environments, offering automatic certificate management for containerized applications. Certbot, on the other hand, provides a more versatile solution for various web server setups but may require more manual configuration. ACME Companion simplifies the process in Docker ecosystems, while Certbot offers greater flexibility across different platforms and server configurations.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Tests GitHub release Docker Image Size Docker stars Docker pulls

acme-companion is a lightweight companion container for nginx-proxy.

It handles the automated creation, renewal and use of SSL certificates for proxied Docker containers through the ACME protocol.

Features:

  • Automated creation/renewal of Let's Encrypt (or other ACME CAs) certificates using acme.sh.
  • Let's Encrypt / ACME domain validation through HTTP-01 (by default) or DNS-01 challenge.
  • Automated update and reload of nginx config on certificate creation/renewal.
  • Support creation of Multi-Domain (SAN) Certificates.
  • Support creation of Wildcard Certificates (with DNS-01 challenge only).
  • Creation of a strong RFC7919 Diffie-Hellman Group at startup.
  • Work with all versions of docker.

HTTP-01 challenge requirements:

  • Your host must be publicly reachable on both port 80 and 443.
  • Check your firewall rules and do not attempt to block port 80 as that will prevent HTTP-01 challenges from completing.
  • For the same reason, you can't use nginx-proxy's HTTPS_METHOD=nohttp.
  • The (sub)domains you want to issue certificates for must correctly resolve to the host.
  • If your (sub)domains have AAAA records set, the host must be publicly reachable over IPv6 on port 80 and 443.

If you can't meet these requirements, you can use the DNS-01 challenge instead. Please refer to the documentation for more information.

In addition to the above, please ensure that your DNS provider answers correctly to CAA record requests. If your DNS provider answer with an error, Let's Encrypt won't issue a certificate for your domain. Let's Encrypt do not require that you set a CAA record on your domain, just that your DNS provider answers correctly.

schema

Basic usage (with the nginx-proxy container)

Three writable volumes must be declared on the nginx-proxy container so that they can be shared with the acme-companion container:

  • /etc/nginx/certs to store certificates and private keys (readonly for the nginx-proxy container).
  • /usr/share/nginx/html to write http-01 challenge files.

Additionally, a fourth volume must be declared on the acme-companion container to store acme.sh configuration and state: /etc/acme.sh.

Please also read the doc about data persistence.

Example of use:

Step 1 - nginx-proxy

Start nginx-proxy with the three additional volumes declared:

$ 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

Binding the host docker socket (/var/run/docker.sock) inside the container to /tmp/docker.sock is a requirement of nginx-proxy.

Step 2 - acme-companion

Start the acme-companion container, getting the volumes from nginx-proxy with --volumes-from:

$ 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 "DEFAULT_EMAIL=mail@yourdomain.tld" \
    nginxproxy/acme-companion

The host docker socket has to be bound inside this container too, this time to /var/run/docker.sock.

Albeit optional, it is recommended to provide a valid default email address through the DEFAULT_EMAIL environment variable, so that Let's Encrypt can warn you about expiring certificates and allow you to recover your account.

Step 3 - proxied container(s)

Once both nginx-proxy and acme-companion containers are up and running, start any container you want proxied with environment variables VIRTUAL_HOST and LETSENCRYPT_HOST both set to the domain(s) your proxied container is going to use.

VIRTUAL_HOST control proxying by nginx-proxy and LETSENCRYPT_HOST control certificate creation and SSL enabling by acme-companion.

Certificates will only be issued for containers that have both VIRTUAL_HOST and LETSENCRYPT_HOST variables set to domain(s) that correctly resolve to the host, provided the host is publicly reachable.

$ docker run --detach \
    --name your-proxied-app \
    --env "VIRTUAL_HOST=subdomain.yourdomain.tld" \
    --env "LETSENCRYPT_HOST=subdomain.yourdomain.tld" \
    nginx

The containers being proxied must expose the port to be proxied, either by using the EXPOSE directive in their Dockerfile or by using the --expose flag to docker run or docker create.

If the proxied container listen on and expose another port than the default 80, you can force nginx-proxy to use this port with the VIRTUAL_PORT environment variable.

Example using Grafana (expose and listen on port 3000):

$ docker run --detach \
    --name grafana \
    --env "VIRTUAL_HOST=othersubdomain.yourdomain.tld" \
    --env "VIRTUAL_PORT=3000" \
    --env "LETSENCRYPT_HOST=othersubdomain.yourdomain.tld" \
    --env "LETSENCRYPT_EMAIL=mail@yourdomain.tld" \
    grafana/grafana

Repeat Step 3 for any other container you want to proxy.

Additional documentation

Please check the docs section.