strangefog/nginx-lets-encrypt repository overview

This image contains Nginx HTTP server along with Let's Encrypt Certbot software so you easly run your HTTP server/proxy with persitable and auto renewable SSL certificates.

THIS IMAGE CAN BE DEPLOYED IN AZURE AND USE AZURE FILES SHARES TO STORE CERTIFICATES (read more about it below)

⁠Example usage:

⁠Create you container and mount all volumes

Let's create container named nginx that will have three mounted volumes:

1. /host/path/nginx mounted as /etc/nginx/conf.d - here all your Nginx configuration will be available
2. /host/path/letsencrypt mounted as /etc/letsencrypt - here all your Let's Encrypt configuration will be available (warning: that will include private keys, so ensure it's secure location)
3. /host/path/www mounted as /srv/www - here you can keep your served files (you can mount as many of these as you want or none at all, it depends on your scenario)

We will also expose ports 80 and 443.

docker run --name nginx -d -p 80:80 -p 443:443 -v /host/path/nginx:/etc/nginx/conf.d -v /host/path/letsencrypt:/etc/letsencrypt -v /host/path/www:/srv/www strangefog/nginx-lets-encrypt:latest

Your HTTP server should be now up and running and you can test it by going to http://localhost - it should display the standard Nginx Welcome page.

⁠Create some domain bound site

Go to the /host/path/nginx folder on your host machine. It's the folder we've mounted in previous step as /etc/nginx it will be pre-populated for you with default nginx configuration files.

Create new site's config file, something like mysite.conf. Content of this file is up to you, but for demonstration let's start with basic one (assume that we're setting up site for mysite.mydomain.com domain):

server {
    server_name  mysite.mydomain.com;

    location / {
        root   /srv/www;
        index  index.html index.htm;
    }

    error_page   500 502 503 504  /50x.html;
    
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

After saving this file restart your nginx container with docker restart nginx and you should be able to navigate to http://mysite.mydomain.com.

⁠Obtain Let's Encrypt SSL certificate

For this step you need to access console inside your container. So make sure nginx container is running and then execute this:

docker exec -it nginx /bin/bash

That will open new bash console inside your container, from there you can call certbot to setup your SSL certificate:

certbot --nginx

Follow the on-screen wizard to complete the process. After that do exit and restart your container once more with docker restart nginx.

From now on you should be able to go to https://mysite.mydomain.com and your new SSL certificate should be working. It should also auto-renew each 90 days or so.

⁠Certificates archive mode (a.k.a. Azure workaround mode)

Standard way of preserving your certificates is, like shown above, to mount volume to the /etc/letsencrypt folder. Unfortunatelly this will not work with Azure File Shares as Certbot is creating symlinks in that folder and symlinks are not supported in Azure Files when used within Azure Container Instances.

To overcome that special mode is available in this image, that will archive to and restore from tarball archive instead of directly using /etc/letsencrypt mount. To use it you need to:

1. Not mount /etc/letsencrypt volume
2. Instead of that mount /etc/letsencrypt-archive
3. Add environment variable USE_CERTS_ARCHIVE=1

So your docker run call should look like this now: docker run --name nginx -d -p 80:80 -p 443:443 -e USE_CERTS_ARCHIVE=1 -v /host/path/nginx:/etc/nginx/conf.d -v /host/path/letsencrypt:/etc/letsencrypt-archive -v /host/path/www:/srv/www strangefog/nginx-lets-encrypt:latest

Or, if you deploy from Azure template:

{
    "apiVersion": "2018-09-01",
    "location": "YOUR_REGION",
    "name": "YOUR_CONTAINERS_GROUP_NAME",
    "properties": {
      "containers": [
        {
          "name": "nginx",
          "properties": {
            "image": "strangefog/nginx-lets-encrypt:latest",
            "environmentVariables" : [{
              "name": "USE_CERTS_ARCHIVE",
              "value": "1"
            }],
            "ports": [
              {
                "port": 80,
                "protocol": "TCP"
              },
              {
                "port": 443,
                "protocol": "TCP"
              }
            ],
            "volumeMounts": [
              {
                "name": "nginx-config",
                "mountPath": "/etc/nginx/conf.d"
              },
              {
                "name": "nginx-certs",
                "mountPath": "/etc/letsencrypt-archive"
              }
            ],
            "resources": {
              "requests": {
                "cpu": 1,
                "memoryInGB": 0.5
              }
            }
          }
        }
      ],
      "ipAddress": {
        "type": "Public",
        "ports": [
          {
            "protocol": "tcp",
            "port": "80"
          },
          {
            "protocol": "tcp",
            "port": "443"
          }
        ]
      },
      "volumes": [
        {
          "name": "nginx-config",
          "azureFile": {
            "shareName": "YOUR_SHARE_NAME_FOR_CONFIGS",
            "storageAccountName": "YOUR_STORAGE_ACCOUNT_NAME",
            "storageAccountKey": "YOUR_STORAGE_ACCOUNT_KEY"
          }
        },
        {
          "name": "nginx-certs",
          "azureFile": {
            "shareName": "YOUR_SHARE_NAME_FOR_CERTS",
            "storageAccountName": "YOUR_STORAGE_ACCOUNT_NAME",
            "storageAccountKey": "YOUR_STORAGE_ACCOUNT_KEY"
          }
        }
      ],
      "osType": "Linux",
      "restartPolicy": "Always"
    },
    "tags": null,
    "type": "Microsoft.ContainerInstance/containerGroups"
  }

With all that in place, each time you will run certbot (or it's run automatically by cron or something), a tarball archive will be created or updated on your mount, with full contents of real /etc/letsencrypt folder. Then, next time container is restarted, startup script will check for existence of that tarball and if it's there, it will be unarchived back into /etc/letsencrypt folder thus restoring your certificates state.