</span></code></pre></div><h2id=parameters>Parameters<aclass=headerlinkhref=#parameterstitle="Permanent link">¶</a></h2><p>Container images are configured using parameters passed at runtime (such as those above). These parameters are separated by a colon and indicate <code><external>:<internal></code> respectively. For example, <code>-p 8080:80</code> would expose port <code>80</code> from inside the container to be accessible from the host's IP on port <code>8080</code> outside the container.</p><table><thead><tr><thstyle="text-align: center;">Parameter</th><th>Function</th></tr></thead><tbody><tr><tdstyle="text-align: center;"><code>-p 443</code></td><td>Https port</td></tr><tr><tdstyle="text-align: center;"><code>-p 80</code></td><td>Http port (required for http validation and http -> https redirect)</td></tr><tr><tdstyle="text-align: center;"><code>-e PUID=1000</code></td><td>for UserID - see below for explanation</td></tr><tr><tdstyle="text-align: center;"><code>-e PGID=1000</code></td><td>for GroupID - see below for explanation</td></tr><tr><tdstyle="text-align: center;"><code>-e TZ=Europe/London</code></td><td>Specify a timezone to use EG Europe/London.</td></tr><tr><tdstyle="text-align: center;"><code>-e URL=yourdomain.url</code></td><td>Top url you have control over (<code>customdomain.com</code> if you own it, or <code>customsubdomain.ddnsprovider.com</code> if dynamic dns).</td></tr><tr><tdstyle="text-align: center;"><code>-e SUBDOMAINS=www,</code></td><td>Subdomains you'd like the cert to cover (comma separated, no spaces) ie. <code>www,ftp,cloud</code>. For a wildcard cert, set this <em>exactly</em> to <code>wildcard</code> (wildcard cert is available via <code>dns</code> and <code>duckdns</code> validation only)</td></tr><tr><tdstyle="text-align: center;"><code>-e VALIDATION=http</code></td><td>Certbot validation method to use, options are <code>http</code>, <code>dns</code> or <code>duckdns</code> (<code>dns</code> method also requires <code>DNSPLUGIN</code> variable set) (<code>duckdns</code> method requires <code>DUCKDNSTOKEN</code> variable set, and the <code>SUBDOMAINS</code> variable must be either empty or set to <code>wildcard</code>).</td></tr><tr><tdstyle="text-align: center;"><code>-e DNSPLUGIN=cloudflare</code></td><td>Required if <code>VALIDATION</code> is set to <code>dns</code>. Options are <code>aliyun</code>, <code>cloudflare</code>, <code>cloudxns</code>, <code>cpanel</code>, <code>digitalocean</code>, <code>dnsimple</code>, <code>dnsmadeeasy</code>, <code>domeneshop</code>, <code>gandi</code>, <code>google</code>, <code>inwx</code>, <code>linode</code>, <code>luadns</code>, <code>nsone</code>, <code>ovh</code>, <code>rfc2136</code>, <code>route53</code> and <code>transip</code>. Also need to enter the credentials into the corresponding ini (or json for some plugins) file under <code>/config/dns-conf</code>.</td></tr><tr><tdstyle="text-align: center;"><code>-e PROPAGATION=</code></td><td>Optionally override (in seconds) the default propagation time for the dns plugins.</td></tr><tr><tdstyle="text-align: center;"><code>-e DUCKDNSTOKEN=</code></td><td>Required if <code>VALIDATION</code> is set to <code>duckdns</code>. Retrieve your token from https://www.duckdns.org</td></tr><tr><tdstyle="text-align: center;"><code>-e EMAIL=</code></td><td>Optional e-mail address used for cert expiration notifications.</td></tr><tr><tdstyle="text-align: center;"><code>-e ONLY_SUBDOMAINS=false</code></td><td>If you wish to get certs only for certain subdomains, but not the main domain (main domain may be hosted on another machine and cannot be validated), set this to <code>true</code></td></tr><tr><tdstyle="text-align: center;"><code>-e EXTRA_DOMAINS=</code></td><td>Additional fully qualified domain names (comma separated, no spaces) ie. <code>extradomain.com,subdomain.anotherdomain.org,*.anotherdomain.org</code></td></tr><tr><tdstyle="text-align: center;"><code>-e STAGING=false</code></td><td>Set to
</span></code></pre></div><p>Will set the environment variable <code>PASSWORD</code> based on the contents of the <code>/run/secrets/mysecretpassword</code> file.</p><h2id=umask-for-running-applications>Umask for running applications<aclass=headerlinkhref=#umask-for-running-applicationstitle="Permanent link">¶</a></h2><p>For all of our images we provide the ability to override the default umask settings for services started within the containers using the optional <code>-e UMASK=022</code> setting. Keep in mind umask is not chmod it subtracts from permissions based on it's value it does not add. Please read up <ahref=https://en.wikipedia.org/wiki/Umask>here</a> before asking for support.</p><h2id=user-group-identifiers>User / Group Identifiers<aclass=headerlinkhref=#user-group-identifierstitle="Permanent link">¶</a></h2><p>When using volumes (<code>-v</code> flags) permissions issues can arise between the host OS and the container, we avoid this issue by allowing you to specify the user <code>PUID</code> and group <code>PGID</code>.</p><p>Ensure any volume directories on the host are owned by the same user you specify and any permissions issues will vanish like magic.</p><p>In this instance <code>PUID=1000</code> and <code>PGID=1000</code>, to find yours use <code>id user</code> as below:</p><divclass="language-text highlight"><pre><span></span><code><spanid=__span-3-1><aid=__codelineno-3-1name=__codelineno-3-1href=#__codelineno-3-1></a> $ id username
</span></code></pre></div><p> </p><h2id=application-setup>Application Setup<aclass=headerlinkhref=#application-setuptitle="Permanent link">¶</a></h2><h3id=validation-and-initial-setup>Validation and initial setup<aclass=headerlinkhref=#validation-and-initial-setuptitle="Permanent link">¶</a></h3><ul><li>Before running this container, make sure that the url and subdomains are properly forwarded to this container's host, and that port 443 (and/or 80) is not being used by another service on the host (NAS gui, another webserver, etc.).</li><li>For <code>http</code> validation, port 80 on the internet side of the router should be forwarded to this container's port 80</li><li>For <code>dns</code> validation, make sure to enter your credentials into the corresponding ini (or json for some plugins) file under <code>/config/dns-conf</code></li><li>Cloudflare provides free accounts for managing dns and is very easy to use with this image. Make sure that it is set up for "dns only" instead of "dns + proxy"</li><li>Google dns plugin is meant to be used with "Google Cloud DNS", a paid enterprise product, and not for "Google Domains DNS"</li><li>For <code>duckdns</code> validation, either leave the <code>SUBDOMAINS</code> variable empty or set it to <code>wildcard</code>, and set the <code>DUCKDNSTOKEN</code> variable with your duckdns token. Due to a limitation of duckdns, the resulting cert will only cover either main subdomain (ie. <code>yoursubdomain.duckdns.org</code>), or sub-subdomains (ie. <code>*.yoursubdomain.duckdns.org</code>), but will not both at the same time. You can use our <ahref=https://hub.docker.com/r/linuxserver/duckdns/>duckdns image</a> to update your IP on duckdns.org.</li><li><code>--cap-add=NET_ADMIN</code> is required for fail2ban to modify iptables</li><li>If you need a dynamic dns provider, you can use the free provider duckdns.org where the <code>URL</code> will be <code>yoursubdomain.duckdns.org</code> and the <code>SUBDOMAINS</code> can be <code>www,ftp,cloud</code> with http validation, or <code>wildcard</code> with dns validation.</li><li>After setup, navigate to <code>https://yourdomain.url</code> to access the default homepage (http access through port 80 is disabled by default, you can enable it by editing the default site config at <code>/config/nginx/site-confs/default</code>).</li><li>Certs are checked nightly and if expiration is within 30 days, renewal is attempted. If your cert is about to expire in less than 30 days, check the logs under <code>/config/log/letsencrypt</code> to see why the renewals have been failing. It is recommended to input your e-mail in docker parameters so you receive expiration notices from Let's Encrypt in those circumstances.</li></ul><h3id=security-and-password-protection>Security and password protection<aclass=headerlinkhref=#security-and-password-protectiontitle="Permanent link">¶</a></h3><ul><li>The container detects changes to url and subdomains, revokes existing certs and generates new ones during start.</li><li>The container provides a pre-generated 4096-bit dhparams.pem (rotated weekly via <ahref=https://ci.linuxserver.io/blue/organizations/jenkins/Xtras-Builders-Etc%2Fdhparams-uploader/activity>Jenkins job</a>) for new instances, however you may generate your own by running <code>docker exec letsencrypt openssl dhparam -out /config/nginx/dhparams.pem 4096</code> WARNING: This takes a very long time</li><li>If you'd like to password protect your sites, you can use htpasswd. Run the following command on your host to generate the htpasswd file <code>docker exec -it letsencrypt htpasswd -c /config/nginx/.htpasswd <username></code></li><li>You can add multiple user:pass to <code>.htpasswd</code>. For the first user, use the above command, for others, use the above command without the <code>-c</code> flag, as it will force deletion of the existing <code>.htpasswd</code> and creation of a new one</li><li>You can also use ldap auth for security and access control. A sample, user configurable ldap.conf
</span></code></pre></div></li></ul><p><strong>Note:</strong> We do not endorse the use of Watchtower as a solution to automated updates of existing Docker containers. In fact we generally discourage automated updates. However, this is a useful tool for one-time manual updates of containers where you have forgotten the original parameters. In the long term, we highly recommend using Docker Compose.</p><ul><li>You can also remove the old dangling images: <code>docker image prune</code></li></ul><h2id=building-locally>Building locally<aclass=headerlinkhref=#building-locallytitle="Permanent link">¶</a></h2><p>If you want to make local modifications to these images for development purposes or just to customize the logic: <divclass="language-text highlight"><pre><span></span><code><spanid=__span-5-1><aid=__codelineno-5-1name=__codelineno-5-1href=#__codelineno-5-1></a>git clone https://github.com/linuxserver/docker-letsencrypt.git
</span></code></pre></div></p><p>The ARM variants can be built on x86_64 hardware using <code>multiarch/qemu-user-static</code><divclass="language-text highlight"><pre><span></span><code><spanid=__span-6-1><aid=__codelineno-6-1name=__codelineno-6-1href=#__codelineno-6-1></a>docker run --rm --privileged multiarch/qemu-user-static:register --reset
</span></code></pre></div></p><p>Once registered you can define the dockerfile to use with <code>-f Dockerfile.aarch64</code>.</p><h2id=versions>Versions<aclass=headerlinkhref=#versionstitle="Permanent link">¶</a></h2><ul><li><strong>28.07.20:</strong> - Start transition to new name, SWAG.</li><li><strong>17.06.20:</strong> - Reformat ssl.conf. Pull in pre-generated dhparams.pem from DO Spaces. Deprecate <code>DHLEVEL</code> param.</li><li><strong>01.06.20:</strong> - Rebasing to alpine 3.12, change ldap login address to <code>/ldaplogin</code> to avoid clashes (existing users need to manually update).</li><li><strong>31.05.20:</strong> - Tweak Authelia confs (existing users can delete <code>authelia-server.conf</code> and <code>authelia-location.conf</code>, and restart to update).</li><li><strong>23.05.20:</strong> - Add support for Authelia.</li><li><strong>15.05.20:</strong> - Remove <code>php7-pecl-imagick</code> due to upstream issues. Add support for <code>Geoip2</code> auto db retrieval.</li><li><strong>10.05.20:</strong> - Added support for fail2ban deny statements.</li><li><strong>04.05.20:</strong> - Allow for optionally setting propagation time for dns plugins. Add repo version of <code>whois</code> to replace the built-in busybox version. Update <code>jail.local</code> to change default fail2ban ban action to more widely supported <code>iptables-allports</code>.</li><li><strong>13.04.20:</strong> - Update cloudflare.ini with token info.</li><li><strong>11.03.20:</strong> - Add php7-sodium.</li><li><strong>06.03.20:</strong> - Implement cert renewal attempt during container start (only if the cert is already expired or will expire within the next 24 hours, otherwise it will be attempted at 2:08am).</li><li><strong>05.03.20:</strong> - Use port and proto upstream variables for ldap and default sample confs.</li><li><strong>24.02.20:</strong> - Remove world/group read permissions in dns-conf.</li><li><strong>23.02.20:</strong> - Add aliyun dns validation plugin.</li><li><strong>28.01.20:</strong> - Deprecate tls-sni validation method, remove from docs.</li><li><strong>27.01.20:</strong> - Add support for cpanel dns validation.</li><li><strong>10.01.20:</strong> - Add support for domeneshop dns validation.</li><li><strong>07.01.20:</strong> - Update ciphers from Mozilla ssl-config recommendations.</li><li><strong>01.01.20:</strong> - Add support for gandi dns validation.</li><li><strong>31.12.19:</strong> - GeoIP2 databases now require personal license keys to download. Auto download is disabled and log message is added.</li><li><strong>19.12.19:</strong> - Rebasing to alpine 3.11.</li><li><strong>19.12.19:</strong> - Increase large_client_header_buffers in nginx.conf to prevent 414 errors.</li><li><strong>18.12.19:</strong> - Add php7-imap and php7-pecl-apcu.</li><li><strong>11.12.19:</strong> - Fix Google Cloud DNS to use .json file for authentication.</li><li><strong>20.11.19:</strong> - Fix cryptography version mismatch due to pip issue.</li><li><strong>17.11.19:</strong> - Add php7-pdo_odbc.</li><li><strong>17.11.19:</strong> - Add transip dns validation plugin.</li><li><strong>27.10.19:</strong> - Turn off lua resty core to get rid of error message in the log (existing users will have to delete <code>/config/nginx/nginx.conf</code> and restart the container).</li><li><strong>26.10.19:</strong> - Add new package for stream-geoip2, remove geoip2 module patch.</li><li><strong>24.10.19:</strong> - Add php7-pecl-imagick.</li><li><strong>23.10.19:</strong> - Update Host header in <code>proxy.conf</code> to fix CSRF issues.</li><li><strong>12.10.19:</strong> - Add linode dns validation plugin.</li><li><strong>23.09.19:</strong> - Move GeoIP2 db to /config to make it persistent.</li><li><strong>14.08.19:</strong> - Add inwx dns validation plugin.</li><li><strong>06.08.19:</strong> - Add php7-ftp.</li><li><strong>04.08.19:</strong> - Add php7-bcmath, php7-pear, php7-xmlrpc.</li><li><strong>02.08.19:</strong> - Add php7-ldap, remove geoip v1(deprecated).</li><li><st
