Merge pull request #14 from voxpupuli/updates

updates to documentation and variable naming

README.md

@@ -6,8 +6,62 @@
 
 This project hosts the Dockerfile and the required scripts to build a Puppet Server container image.
 
+You can run a copy of Puppet Server with the following Docker command:
+
+```bash
+docker run --name puppet --hostname puppet voxpupuli/container-puppetserver:7.13.0
+```
+
+Although it is not strictly necessary to name the container `puppet`, this is
+useful when working with the other Puppet images, as they will look for a server
+on that hostname by default.
+
+If you would like to start the Puppet Server with your own Puppet code, you can
+mount your own directory at `/etc/puppetlabs/code`:
+
+    docker run --name puppet --hostname puppet -v ./code:/etc/puppetlabs/code/ voxpupuli/container-puppetserver:7.13.0
+
 For compose file see: [CRAFTY](https://github.com/voxpupuli/crafty/tree/main/puppet/oss)
 
+You can find out more about Puppet Server in the [official documentation](https://www.puppet.com/docs/puppet/7/server/about_server.html).
+
+
+## Configuration
+
+The following environment variables are supported:
+
+| Name                                       | Usage / Default                                                                                                                                               |
+|--------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **PUPPETSERVER_HOSTNAME**                  | The DNS name used on the servers SSL certificate - sets the `certname` and `server` in puppet.conf<br><br>Defaults to unset.                                  |
+| **DNS_ALT_NAMES**                          | Additional DNS names to add to the servers SSL certificate<br>**Note** only effective on initial run when certificates are generated                          |
+| **PUPPETSERVER_PORT**                      | The port of the puppetserver<br><br>`8140`                                                                                                                    |
+| **AUTOSIGN**                               | Whether or not to enable autosigning on the puppetserver instance. Valid values are `true`, `false`, and `/path/to/autosign.conf`.<br><br>Defaults to `true`. |
+| **CA_ENABLED**                             | Whether or not this puppetserver instance has a running CA (Certificate Authority)<br><br>`true`                                                              |
+| **CA_HOSTNAME**                            | The DNS hostname for the puppetserver running the CA. Does nothing unless `CA_ENABLED=false`<br><br>`puppet`                                                  |
+| **CA_PORT**                                | The listening port of the CA. Does nothing unless `CA_ENABLED=false`<br><br>`8140`                                                                            |
+| **CA_ALLOW_SUBJECT_ALT_NAMES**             | Whether or not SSL certificates containing Subject Alternative Names should be signed by the CA. Does nothing unless `CA_ENABLED=true`.<br><br>`false`        |
+| **PUPPET_REPORTS**                         | Sets `reports` in puppet.conf<br><br>`puppetdb`                                                                                                               |
+| **PUPPET_STORECONFIGS**                    | Sets `storeconfigs` in puppet.conf<br><br>`true`                                                                                                              |
+| **PUPPET_STORECONFIGS_BACKEND**            | Sets `storeconfigs_backend` in puppet.conf<br><br>`puppetdb`                                                                                                  |
+| **PUPPETSERVER_MAX_ACTIVE_INSTANCES**      | The maximum number of JRuby instances allowed<br><br>`1`                                                                                                      |
+| **PUPPETSERVER_MAX_REQUESTS_PER_INSTANCE** | The maximum HTTP requests a JRuby instance will handle in its lifetime (disable instance flushing)<br><br>`0`                                                 |
+| **PUPPETSERVER_JAVA_ARGS**                 | Arguments passed directly to the JVM when starting the service<br><br>`-Xms512m -Xmx512m`                                                                     |
+| **USE_PUPPETDB**                           | Whether to connect to puppetdb<br>Sets `PUPPET_REPORTS` to `log` and `PUPPET_STORECONFIGS` to `false` if those unset<br><br>`true`                            |
+| **PUPPETDB_SERVER_URLS**                   | The `server_urls` to set in `/etc/puppetlabs/puppet/puppetdb.conf`<br><br>`https://puppetdb:8081`                                                             |
+| **PUPPETDB_HOSTNAME**                      | The DNS name of the puppetdb <br><br> Defaults to `puppetdb`                                                                                                  |
+| **PUPPETDB_SSL_PORT**                      | The TLS port of the puppetdb <br><br> Defaults to `8081`                                                                                                      |
+
+## Initialization Scripts
+
+If you would like to do additional initialization, add a directory called `/docker-custom-entrypoint.d/` and fill it with `.sh` scripts.
+These scripts will be executed at the end of the entrypoint script, before the service is ran.
+
+## Persistance
+
+If you plan to use the in-server CA, restarting the container can cause the server's keys and certificates to change, causing agents and the server to stop trusting each other.
+To prevent this, you can persist the default cadir, `/etc/puppetlabs/puppetserver/ca`.
+For example, `docker run -v $PWD/ca-ssl:/etc/puppetlabs/puppetserver/ca voxpupuli/container-puppetserver:7.13.0`.
+
 ## How to build the container
 
 [see here](https://github.com/voxpupuli/crafty/blob/main/docs/how-to-build.md)

puppetserver/Dockerfile

@@ -23,15 +23,15 @@ ENV PUPPETSERVER_JAVA_ARGS="-Xms1024m -Xmx1024m" \
     PATH=/opt/puppetlabs/server/bin:/opt/puppetlabs/puppet/bin:/opt/puppetlabs/bin:$PATH \
     SSLDIR=/etc/puppetlabs/puppet/ssl \
     LOGDIR=/var/log/puppetlabs/puppetserver \
-    PUPPETSERVER_HOSTNAME="" \
+    PUPPETSERVER_HOSTNAME="puppet" \
     DNS_ALT_NAMES="" \
-    PUPPET_MASTERPORT=8140 \
-    AUTOSIGN="" \
+    PUPPETSERVER_PORT=8140 \
+    AUTOSIGN=true \
     PUPPETSERVER_MAX_ACTIVE_INSTANCES=1 \
     PUPPETSERVER_MAX_REQUESTS_PER_INSTANCE=0 \
     CA_ENABLED=true \
     CA_HOSTNAME=puppet \
-    CA_MASTERPORT=8140 \
+    CA_PORT=8140 \
     CA_ALLOW_SUBJECT_ALT_NAMES=false \
     USE_PUPPETDB=true \
     PUPPETDB_SERVER_URLS=https://puppetdb:8081 \

puppetserver/docker-entrypoint.d/55-set-masterport.sh

@@ -4,8 +4,8 @@ hocon() {
   /opt/puppetlabs/puppet/lib/ruby/vendor_gems/bin/hocon "$@"
 }
 
-if test -n "$PUPPET_MASTERPORT"; then
+if test -n "$PUPPETSERVER_PORT"; then
   cd /etc/puppetlabs/puppetserver/conf.d/
-  hocon -f webserver.conf set webserver.ssl-port $PUPPET_MASTERPORT
+  hocon -f webserver.conf set webserver.ssl-port $PUPPETSERVER_PORT
   cd /
 fi

puppetserver/docker-entrypoint.d/80-ca.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 ca_running() {
-  status=$(curl --silent --fail --insecure "https://${CA_HOSTNAME}:${CA_MASTERPORT}/status/v1/simple")
+  status=$(curl --silent --fail --insecure "https://${CA_HOSTNAME}:${CA_PORT:-8140}/status/v1/simple")
   test "$status" = "running"
 }
 
@@ -36,7 +36,7 @@ EOF
       sleep 1
     done
 
-    puppet ssl bootstrap --server="${CA_HOSTNAME}" --masterport="${CA_MASTERPORT}"
+    puppet ssl bootstrap --server="${CA_HOSTNAME}" --masterport="${CA_PORT:-8140}"
   fi
 else
   # we are the CA

puppetserver/docker-entrypoint.d/90-log-config.sh

@@ -12,7 +12,7 @@ else
   echo "* PUPPETSERVER_HOSTNAME: unset"
   certname=$(cd "${SSLDIR}/certs" && ls *.pem | grep --invert-match ca.pem)
 fi
-echo "* PUPPET_MASTERPORT: '${PUPPET_MASTERPORT}'"
+echo "* PUPPETSERVER_PORT: '${PUPPETSERVER_PORT:-8140}'"
 echo "* Certname: '${certname}'"
 echo "* DNS_ALT_NAMES: '${DNS_ALT_NAMES}'"
 echo "* SSLDIR: '${SSLDIR}'"

puppetserver/healthcheck.sh

@@ -13,10 +13,10 @@ certname=$(cd "${SSLDIR}/certs" && ls *.pem | grep --invert-match ca.pem)
 curl --fail \
     --no-progress-meter \
     --max-time ${timeout} \
-    --resolve "${HOSTNAME}:${PUPPET_MASTERPORT}:127.0.0.1" \
+    --resolve "${HOSTNAME}:${PUPPETSERVER_PORT:-8140}:127.0.0.1" \
     --cert    "${SSLDIR}/certs/$certname" \
     --key     "${SSLDIR}/private_keys/$certname" \
     --cacert  "${SSLDIR}/certs/ca.pem" \
-    "https://${HOSTNAME}:${PUPPET_MASTERPORT}/status/v1/simple" \
+    "https://${HOSTNAME}:${PUPPETSERVER_PORT:-8140}/status/v1/simple" \
     |  grep -q '^running$' \
     || exit 1