diff --git a/LICENSE b/LICENSE index a4be403..e1bcebe 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2020 Ben Green +Copyright (c) 2021 Ben Green Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index c4ac628..e29bd21 100644 --- a/README.md +++ b/README.md @@ -4,31 +4,55 @@ [Docker Repository](https://hub.docker.com/r/bcgdesign/nginx-proxy) - [bcg|design ecosystem](https://github.com/bencgreen/docker) -Nginx Proxy which uses [getssl](https://github.com/srvrco/getssl) to automate requesting and renewing SSL certificates via Let's Encrypt. +Nginx Proxy which uses [getssl](https://github.com/srvrco/getssl) to automate requesting and renewing SSL certificates via Let's Encrypt. Certificates are checked for renewal every week - the last check can be viewed in the `/ssl` volume. ## Ports +For SSL certificate requests to work correctly, ports 80 and 443 need mapping from the host to your proxy container, e.g. adding `"0.0.0.0:80:80"` to the ports section of your docker compose file. + * 80 (from base image) * 443 -## Environment Variables - -Required: +## Volumes -```bash -LETS_ENCRYPT_EMAIL= # used for renewal notification emails -``` +| Volume | Purpose | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `/www` | *From base image* | +| `/sites` | Nginx site configuration, auto-generated on first run based on `conf.sh`. After they are generated, you can alter them to suit their needs. Running `nginx-regenerate` will wipe them all and start again. | +| `/ssl` | Contains auto-generated SSL configuration and certificates (for backup purposes). Your `conf.sh` file should be stored in here for auto-configuration (see `ssl-conf-sample.sh`). Certificate update log (`update.log`) will be created here weekly. | -Optional: +## Environment Variables -```bash -CLEAN_INSTALL=0 # clean all config and certificates before doing anything else -LETS_ENCRYPT_LIVE=0 # set to 1 to use live instead of staging server -SSL_DHPARAM_BITS=4096 # set to the number of bits to use for generating DH parameters -SSL_REDIRECT_INSECURE=0 # HTTPS redirection -SSL_REDIRECT_TO_CANONICAL=0 # canonical domain name redirection -SSL_REQUEST_ON_STARTUP=0 # automatically request certificates on startup -``` +| Variable | Values | Description | Default | +| ------------------------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| `LETS_ENCRYPT_EMAIL` | A valid email address | Used by Lets Encrypt for notification emails. | *None* - **required** | +| `CLEAN_INSTALL` | 0 or 1 | If 1, all Nginx and SSL configuration and certificates will be deleted and regenerated. | 0 | +| `LETS_ENCRYPT_LIVE` | 0 or 1 | Only set to 1 (to request live certificates) when your config is correct - Lets Encrypt rate limit certificate requests. | 0 | +| `SSL_DHPARAM_BITS` | A valid integer | The size of your DHPARAM variables - adjust down only if you have limited processing resources. | 4096 | +| `SSL_REDIRECT_INSECURE` | 0 or 1 | If 1, all insecured (HTTP) requests will be upgraded by Nginx to secure (HTTPS). | 0 | +| `SSL_REDIRECT_TO_CANONICAL` | 0 or 1 | If 1, all requests will be redirected to the primary domain (defined in `conf.sh`). | 0 | +| `SSL_REQUEST_ON_STARTUP` | 0 or 1 | If 1, SSL certificates will be automatically requested - otherwise you'll need to use `ssl-request`. | 0 | +| `GETSSL_SKIP_HTTP_TOKEN_CHECK` | true or false | Set to true to enable `getssl`'s [skip HTTP token check](https://github.com/srvrco/getssl/wiki/Config-variables#skip_http_token_checkfalse). | false | + +## Helper Functions + +| Function | Arguments | Description | +| ------------------ | --------- | ----------------------------------------------------------------------------------- | +| `nginx-regenerate` | *None* | Removes Nginx configuration files (in `/sites`) and regenerates based on `conf.sh`. | +| `ssl-init` | *None* | Initialises SSL configuration based on `conf.sh`. | +| `ssl-regenerate` | *None* | Removes SSL configuration files (in `/ssl`) and regenerates based on `conf.sh`. | +| `ssl-request` | *None* | Requests SSL certificates from Lets Encrypt. | +| `ssl-update` | *None* | Attempts to update SSL certificates manually. | + +## Nginx Configuration Helpers + +The image contains a handful of useful Nginx configuration 'helper' files, which you can find in `/overlay/etc/nginx/helpers`. + +| Helper | Description | +| --------------------- | ---------------------------------------------------------------------------------------------------------------- | +| `proxy-params.conf` | Headers commonly required when proxying a site. | +| `secure-headers.conf` | Standard secure headers - see [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/). | +| `tls1_3-only.conf` | If you want to be ultra-secure (and not support older browsers), this will disable all TLS protocols except 1.3. | ## Authors @@ -40,5 +64,5 @@ SSL_REQUEST_ON_STARTUP=0 # automatically request certificates on startup ## Copyright -> Copyright (c) 2020 Ben Green +> Copyright (c) 2021 Ben Green > Unless otherwise stated diff --git a/VERSION b/VERSION index 1cc5f65..8cfbc90 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.1.0 \ No newline at end of file +1.1.1 \ No newline at end of file diff --git a/overlay/etc/periodic/weekly/update-certs b/overlay/etc/periodic/weekly/update-certs index 763287d..ed7ec6f 100644 --- a/overlay/etc/periodic/weekly/update-certs +++ b/overlay/etc/periodic/weekly/update-certs @@ -1,2 +1,2 @@ -#!/bin/bash -ssl-update +#!/usr/bin/with-contenv bash +ssl-update > ${SSL}/update.log diff --git a/ssl-conf-sample.sh b/ssl-conf-sample.sh index 16722d0..36f5179 100644 --- a/ssl-conf-sample.sh +++ b/ssl-conf-sample.sh @@ -2,7 +2,7 @@ #====================================================================================================================== # This file should be modified to define domain arrays -# and then stored in /ssl/conf/sites.sh +# and then stored in /ssl/conf.sh # # DOMAINS is an associative array # key: (string) primary domain name @@ -12,7 +12,7 @@ # key: (string) primary domain name - if it doesn't match one of the keys in DOMAINS, it will be ignored # value: (string) alias domain names to be included in the SSL certificate, separated by a space # -# These arrays will generate configuration files that will be stored in /ssl/conf +# These arrays will generate configuration files that will be stored in /sites and /ssl/certs # After generation they can be modified to suit your needs - after modification, the container should be restarted #======================================================================================================================