pswerlang/nginx-auto-ssl repository overview

⁠About this fork

This repo was forked from valian/docker-nginx-auto-ssl⁠. I have made the following enhancements:

• Entry Point Change: The original entrypoint.sh has been replaced with entrypoint.py, a Python script that performs the same functionality. This change was made because I am more comfortable using Python for modifications and enhancements.
• Multiline Environment Variable Support: The SITES environment variable can now be specified as a multiline string, which is particularly useful for managing multiple sites to proxy. Please see the format in the example below.
• Multi-Architecture Support: The Docker image has been rebuilt to support both x86 and ARM architectures. The updated image can be found on Docker Hub⁠.

⁠docker-nginx-auto-ssl

The simpliest solution to add SSL cert to your site

Docker image for automatic generation of SSL certs using Let's encrypt and Open Resty, with reasonable SSL settings, HTTP/2 and WebSockets support out-of-the-box. You can specify allowed domains and simple proxies using ENV variables, and easily override nginx.conf to your needs.

This is possible thanks to OpenResty⁠ and lua-resty-auto-ssl⁠.

Image status: used in production. Some backward-compatible changes may be added in the future.

⁠Usage

⁠Quick start

To generate and automatically renew certificates for your application, use the following commands:

# replace these values
export DOMAIN=yourdomain.com
export APP_ADDRESS=localhost:8080

# install docker first, and then run following command
docker run -d \
  --name nginx-auto-ssl \
  --restart on-failure \
  --network host \
  -e ALLOWED_DOMAINS="$DOMAIN" \
  -e SITES="$DOMAIN=$APP_ADDRESS" \
  -v ssl-data:/etc/resty-auto-ssl \
  pswerlang/nginx-auto-ssl

# display logs from container, to check if everything is fine.
docker logs nginx-auto-ssl

Docker-compose⁠ example:

# compose.yaml
services:
  nginx:
    image: pswerlang/nginx-auto-ssl
    restart: on-failure
    ports:
      - 80:80
      - 443:443
    volumes:
      - ssl_data:/etc/resty-auto-ssl
    environment:
      ALLOWED_DOMAINS: 'yourdomain.com'
      SITES: 'yourdomain.com=myapp:80'
  
  # your application, listening on port specified in `SITES` env variable
  myapp:
    image: nginx

volumes:
  ssl_data:

start using

docker-compose up -d

Both cases will work when request to yourdomain.com will reach just-deployed nginx (so when it will be running on your server, with correctly defined DNS entry).

Available configuration options:

⁠Proxying Multiple Sites

If you want to proxy multiple sites, you can run:

# compose.yaml
services:
  nginx:
    image: pswerlang/nginx-auto-ssl
    restart: on-failure
    ports:
      - 80:80
      - 443:443
    environment:
      ALLOWED_DOMAINS: 'example.com'
      SITES: |
        example.com=myapp:80
        api.example.com=api:80
        app.example.com=app:80

⁠Customization

⁠Includes from /etc/nginx/conf.d/*.conf

Additional server blocks are automatically loaded from /etc/nginx/conf.d/*.conf. If you want to provide your own configuration, you can either use volumes or create custom image.

Example server configuration (for example, named server.conf)

server {
  listen 443 ssl default_server;
  
  # remember about this line!
  include resty-server-https.conf;

  location / {
    proxy_pass http://app;
  }
  
  location /api {
    proxy_pass http://api;
  }
}

Volumes method

# compose.yaml
services:
  nginx:
    image: pswerlang/nginx-auto-ssl
    restart: on-failure
    ports:
      - 80:80
      - 443:443
    volumes:
      # instead of . use directory with your configurations
      - .:/etc/nginx/conf.d

Custom image way

FROM pswerlang/nginx-auto-ssl

# instead of . use directory with your configurations
COPY . /etc/nginx/conf.d

docker build -t docker-nginx-auto-ssl .
docker run [YOUR_OPTIONS] docker-nginx-auto-ssl

⁠Using $SITES with your own template

You have to override /usr/local/openresty/nginx/conf/server-proxy.conf either using volume or custom image. Basic templating is implemented for variables $SERVER_NAME and $SERVER_ENDPOINT.

Example template:

server {
  listen 443 ssl;
  server_name $SERVER_NAME;

  include resty-server-https.conf;

  location / {
    proxy_pass http://$SERVER_ENDPOINT;
  }
}

⁠Custom Nginx Configuration

If additional customization is required, you can provide your own Nginx configuration.

Example Dockerfile:

FROM pswerlang/nginx-auto-ssl

COPY nginx.conf /usr/local/openresty/nginx/conf/

Minimal working nginx.conf:

events {
  worker_connections 1024;
}

http {
  
  # required
  include resty-http.conf;

  server {
    listen 443 ssl;
    
    # required
    include resty-server-https.conf;
    
    # you should add your own locations here    
  }

  server {
    listen 80 default_server;
    
    # required
    include resty-server-http.conf;
  }
}

Minimal nginx.conf with support for $SITES and conf.d includes

events {
  worker_connections 1024;
}

http {

  include resty-http.conf;

  server {
    listen 80 default_server;
    include resty-server-http.conf;
  }
  
  # you can insert your blocks here or inside conf.d
  
  include /etc/nginx/conf.d/*.conf;
}

Build and run it using

docker build -t docker-nginx-auto-ssl .
docker run [YOUR_OPTIONS] docker-nginx-auto-ssl

⁠How does it work?

A short walktrough of what's going on here.

• The docker entrypoint⁠ is responsible for preparing a location block for each site declared in SITES env variable. This file is used as a template⁠.
• when request comes to port 80, it's by default redirected to 443 (HTTP -> HTTPS redirection)
• when request comes to port 443, HTTPS certificate is resolved by lua code (relevant file in this repo⁠ and source code from lua-resty-auto-ssl⁠). If certificate exists for a given domain and is valid, it's returned. Otherwise, a process of generating new certificate starts. It's initialized here⁠ and uses https://github.com/dehydrated-io/dehydrated⁠ for all the Let's Encrypt-related communication. It starts challenge process, prepares files for challenge and receives certificates. All of that is done in a couple of seconds, while the original request waits for the response.
• challenge files are prepared and served under /.well-known/acme-challenge/ (relevant file from this repo ⁠ and source code from lua-resty-auto-ssl⁠)

There's more to it, eg locks across all workers to only generate one certificate for a domain at a time, upload of the certificate to shared storage if configured, checking if domain is whitelisted, communication with Let's Encrypt etc. All in all, it's fairly efficient and shouldn't add any noticeable overhead to nginx.

⁠CHANGELOG

• 01-11-2024 - Added multi-architecture support, Python entrypoint, and multiline SITES support
• 11-11-2019 - Added gzip support and dropped TLS 1.0 and 1.1 #33
• 18-04-2019 - Added WebSocket support #22
• 29-05-2017 - Fixed duplicate redirect location after container restart #2
• 19-12-2017 - Support for $SITES variable
• 2-12-2017 - Dropped HSTS by default
• 25-11-2017 - Initial release

⁠LICENCE

MIT