Merge pull request #2 from jreichmann/zeroConf

Tutorial to use docker-dehydrated without any configuration

Dockerfile

@@ -14,11 +14,11 @@ RUN apk update \
 		bash \
 		su-exec \
 		libxml2-utils \
-	&& git clone https://github.com/lukas2511/dehydrated /dehydrated 
+	&& git clone https://github.com/lukas2511/dehydrated /dehydrated
 
+# Add the files in the 'root' folder to the images filesystem
 ADD root /
 
-
 VOLUME /etc/dehydrated
 VOLUME /var/www/dehydrated
 VOLUME /certs

README.md

@@ -0,0 +1,24 @@
+# docker-dehydrated
+
+This is a docker container that wraps around [dehydrated](https://github.com/lukas2511/dehydrated).
+
+## Usage
+
+For a short tutorial on how to use this container with zero-configuration to sign certificates
+using the HTTP-Challenge, see [zero-config-mode.md]("Zero-Config"-Mode).
+
+## Environment variables
+
+The following environment variables can be set to influence the container's behaviour:
+
+- `$ENDPOINT` which ACME-Endpoint you want to use, supported values: "staging", "production" (default).
+- `$CHALLENGE` what type of challenge should be used, supported values: "http-01" (default), "dns-01"
+
+If the environment variables were not explicitely set, no modification to the configuration file is made
+
+## Behaviour on startup
+
+When the container is started, a script is run which looks for the configuration file in the places supported by dehydrated,
+and if no configuration file is found, it will copy the [example configuration file](https://github.com/lukas2511/dehydrated/docs/examples/config)
+into `/etc/dehydrated/config`.
+

root/etc/periodic/weekly/dehydrated

@@ -1,3 +1,4 @@
 #!/bin/bash
 chown -R ${UID}:${GID} /etc/dehydrated /certs /var/www/dehydrated
-su-exec ${UID}:${GID} /dehydrated/dehydrated -c
+# Run dehydrated
+su-exec ${UID}:${GID} /dehydrated/dehydrated --cron --keep-going

root/etc/s6.d/dehydrated/run

@@ -1,3 +1,11 @@
 #!/bin/sh
 s6-svc -O /etc/s6.d/dehydrated
+
+# Set ownership to dehydrated on the relevant folders
+chown -R ${UID}:${GID} /etc/dehydrated /certs /var/www/dehydrated
+
+# Register to the CA
+su-exec ${UID}:${GID} /dehydrated/dehydrated --register --accept-terms
+
+# Run the weekly script once
 /etc/periodic/weekly/dehydrated

root/etc/s6.d/setup/run

@@ -0,0 +1,58 @@
+#!/bin/bash
+s6-svc -O /etc/s6.d/setup
+
+# Check if and which configuration file exists
+CONFIGFILE="none"
+for check_config in "/etc/dehydrated" "/usr/local/etc/dehydrated" "${PWD}" "${SCRIPTDIR}"; do
+	if [[ -f "${check_config}/config" ]]; then
+		CONFIGFILE="${check_config}/config"
+	fi
+done
+
+# At this point, if no configuration file exists, copy the example into /etc/dehydrated
+if [[ "$CONFIGFILE" == "none" ]]; then
+	cp /dehydrated/docs/examples/config /etc/dehydrated/config
+	CONFIGFILE="/etc/dehydrated/config"
+fi
+
+# Determine if the staging endpoint should be used
+case "$ENDPOINT" in
+	"staging")
+		# If CA=... is commented, uncomment and set it to staging, if it is set to production, set it to staging
+		sed -ie 's/#CA=.*$/CA="https:\/\/acme-staging.api.letsencrypt.org\/directory"/g' $CONFIGFILE
+		sed -ie 's/CA=.+acme-v01\.api\..+$/CA="https:\/\/acme-staging.api.letsencrypt.org\/directory"/g' $CONFIGFILE
+		# Same procedure for CA_TERMS=...
+		sed -ie 's/#CA_TERMS=.*$/CA_TERMS="https:\/\/acme-staging.api.letsencrypt.org\/terms"/g' $CONFIGFILE
+		sed -ie 's/CA_TERMS=.+acme-v01\.api\..+$/CA_TERMS="https:\/\/acme-staging.api.letsencrypt.org\/terms"/g' $CONFIGFILE
+	;;
+	"production")
+		# If CA=... is  commented, uncomment and set to production, if it was set to staging, set it to production
+		sed -ie 's/#CA=.*$/CA="https:\/\/acme-v01.api.letsencrypt.org\/directory"/g' $CONFIGFILE
+		sed -ie 's/CA=.+acme-staging\.api\..+$/https:\/\/acme-v01.api.letsencrypt.org\/directory"/g' $CONFIGFILE
+		# Same thing for CA_TERMS=...
+		sed -ie 's/#CA_TERMS=.*$/CA_TERMS="https:\/\/acme-v01.api.letsencrypt.org\/terms"/g' $CONFIGFILE
+		sed -ie 's/CA_TERMS=.+acme-staging\.api\..+$/CA_TERMS="https:\/\/acme-v01.api.letsencrypt.org\/terms"/g' $CONFIGFILE
+	;;
+	*)
+		echo "INFO: No endpoint was specifically set, dehydrated will use its default"
+	;;
+esac
+
+# Determine which type of challenge should be used
+case "$CHALLENGE" in
+	"http-01")
+		# If we have a "fresh" config, uncomment the challengetype-line and set our value
+		sed -ie 's/#CHALLENGETYPE=.*$/CHALLENGETYPE="http-01"/g' $CONFIGFILE
+		# If a challengetype is already set, overwrite it
+		sed -ie 's/CHALLENGETYPE=.+$/CHALLENGETYPE="http-01"/g' $CONFIGFILE
+	;;
+	"dns-01")
+		# If we have the default config, uncomment the line and set our challengetype
+		sed -ie 's/#CHALLENGETYPE=.*$/CHALLENGETYPE="dns-01"/g' $CONFIGFILE
+		# If a challengetype was already set, overwrite it with the new value
+		sed -ie 's/CHALLENGETYPE=.+$/CHALLENGETYPE="dns-01"/g' $CONFIGFILE
+	;;
+	*)
+		echo "INFO: No challenge-type was specified, the default from dehydrated will be used"
+	;;
+esac

zero-config-mode.md

@@ -0,0 +1,46 @@
+# Zero-configuration mode
+
+This is a tutorial on how to use this container (without needing to configure anything) to create
+certificates for a given set of domains (using the HTTP-Challenge).
+
+## Prerequisites
+
+These are the things that you need to setup / already have set up in order to use this container
+for creating certificates using the HTTP-Challenge:
+
+- A working internet connection, obviously
+- HTTP Webserver to serve the ``.well-known`` which is used for the HTTP-Challenge
+
+Now create a folder in which dehydrated can push the challenge-data later, in this tutorial it
+will be called ``dehydrated-www``. Configure your Webserver to serve the contents of this folder
+under ``domain``/.well-known/ (for all domains for which you want to create certificates).
+
+Next create another folder in which dehydrated will place its configuration, certificates etc.,
+in this tutorial it will be called ``dehydrated-data``. In this folder, create a file called
+``domains.txt`` in which you list the domains you want to create certificates for, using the
+following format:
+
+- each domain on a new line
+- subdomains of a domain on the same line as the domain.
+
+For more information on the format, see [https://github.com/lukas2511/dehydrated/blob/master/docs/domains_txt.md](https://github.com/lukas2511/dehydrated/blob/master/docs/domains_txt.md)
+
+## Using docker-dehydrated
+
+Now you can just run the container, and as the default challenge is the HTTP-Challenge, you do
+not need to pass environment variables to alter the default behaviour. To run the container,
+execute:
+
+```bash
+$ docker run -v ./dehydrated-www:/var/www/dehydrated \
+-v ./dehydrated-data:/etc/dehydrated jcgruenhage/dehydrated
+```
+
+Please note that on SELinux-Systems, you need to set the "SELinux"-Flag when passing volumes:
+``./dehydrated-www:/var/www/dehydrated:z`` (analog for ``dehydrated-data``).
+
+Also, the container will ``chown`` the folders passed to himself, so make sure your webserver can
+still serve the contents of ``dehydrated-www``.
+
+After the challenges have been run, the certificates will be stored in ``dehydrated-data/certs``,
+make sure to back this folder up!