mreithub/simple-apache repository overview

⁠simp_le Apache

simp_le Apache is a Docker image providing a relatively basic Apache installation bundled with the simp_le⁠ letsencrypt.org client.

**IMPORTANT: ** Make sure to at least define the /etc/apache2/ssl directory as a persistent volume as there are rate limits on how many certificates can be requested per domain and week on letsencrypt.org (see 1⁠) (so if you re-request them each time you recreate the container, you might hit that limit)

⁠Usage - with bind mounts

Run the following command (I've added newlines here to increase readability):

docker run -d
  -e [email protected] 
  -e SIMPLE_DOMAINS='example.com foo.example.net'
  -p 80:80 -p 443:443
  -v /data/apache/sites/:/etc/apache2/sites-available/
  -v /data/apache/certs/:/etc/apache2/ssl/
  mreithub/simple-apache

Then for each site you want to create add a virtual host configuration (in the above example in /data/apache/sites/); e.g. foo.example.net.conf(make sure the filename ends with .conf or the file will be ignored):

<VirtualHost *:443>
    ServerAdmin webmaster@localhost
    ServerName foo.example.net
    
    DocumentRoot /var/www/foo.example.net/
    
    <Directory /var/www/foo.example.net/>
        Order allow,deny
        Allow from all
        Require all granted
    </Directory>

    # ...

    # This part is crucial:
    SslEngine on
    SSLCertificateFile      /etc/apache2/ssl/fullchain.pem
    SSLCertificateKeyFile   /etc/apache2/ssl/key.pem
</VirtualHost>

Then either restart your container or run

docker exec -ti <containerName> updateSites

to update the list of enabled sites and reload Apache.

⁠Usage - Custom image

If you need additional software for the container (for this example we'll use PHP), create your own image using this one as its base:

FROM mreithub/simple-apache
RUN apt-get install --yes libapache2-mod-php5
RUN a2enmod php5

# ...

Of course you then also put your sites directly into your image then (instead of using volumes)

⁠HTTP sites

If you also want to allow HTTP on a site (and therefore create a :80 VirtualHost config), make sure the letsencrypt can access the challenges at /.well-known/.

This can be done by either specifying the document root in the SIMPLE_DOMAINS variable (format: domainname:documentRoot):

SIMPLE_DOMAINS="... foo.example.net:/var/www/myHttpPage/ ..."

or by making an alias/symlink/...

⁠Environment Variables

• SIMPLE_EMAIL
  letsencrypt.org account e-mail address.

• SIMPLE_DOMAINS
  Space separated list of domain names to fetch certificates for.

• ENABLE_MODULES
  Allows you to activate additional apache modules (just specify them as space separated list)

• SIMPLE_KSPASS
  If present the script will generate/update a keystore.p12 file (in /etc/apache2/ssl/) with the given password

• SIMPLE_TOS If present, use this SHA256 hash instead of the default Terms of Service hash (use this if you get a 'TOS hash mismatch' error)

• SIMPLE_MAIN If present (and set to the hostname of the main server), this container runs in hot-standby mode (for high availability setups).
  In that mode it won't start simp_le but instead periodically download the main server's certificate chain.
  When that's been changed (i.e. the main server renewed its LetsEncrypt certificate) it'll update the local chain and reloads apache.

  Note that you'll have to manually copy the private key file (key.pem) from the main server.

⁠Design choices

• The image is based on Debian Jessie
• Extra sites will only be enabled after the SSL certificates have been fetched
• Only site configurations ending with .conf will be enabled (which allows you to disable a site simply by renaming its config file)
• Certificates are fetched once a month (using a cronjob).
• the sites-enabled/directory is managed. The updateSites script manages its symlinks.
• The default HTTP site (000-default.conf) is configured to provide access to the letsencrypt challenges but will redirect all other traffic to HTTPS
  • The redirect is done using HTTP 302 Found. This will break POST requests issued over HTTP, but that's intentional (Use HTTPS for user data ;). If you can't (e.g. for backwards compatibility reasons), simply create another HTTP that handles things the way you need it to).
• Instead of having separate containers (one for apache/nginx/... and one for simp_le) I chose to bundle them. That way apache can be reloaded automatically after certificates have changed