Top Related Projects
Automated nginx proxy for Docker containers using docker-gen
The Cloud Native Application Proxy
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
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:
- 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:
- Run the containers:
docker-compose up -d
- 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
- Purpose: nginx-proxy focuses on reverse proxy functionality, while acme-companion specializes in SSL/TLS certificate management.
- Integration: acme-companion is designed to work alongside nginx-proxy, providing automated HTTPS support.
- Complexity: nginx-proxy is simpler for basic setups, while acme-companion adds complexity but offers automated SSL/TLS management.
- 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.
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.
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.
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 designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
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) orDNS-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
and443
. - Check your firewall rules and do not attempt to block port
80
as that will preventHTTP-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
and443
.
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.
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 writehttp-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.
Top Related Projects
Automated nginx proxy for Docker containers using docker-gen
The Cloud Native Application Proxy
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
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.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot