glyptodon/guacamole-ssl-nginx is a Dockerized deployment of Nginx, built off Docker's official Nginx image which is pre-configured to provide SSL termination for Guacamole. It supports:
- Automatic retrieval of a certificate from Let's Encrypt.
- Automatic generation of a self-signed certificate.
- Usage of an existing certificate that you have already obtained from a certificate authority.
Starting an Nginx instance for SSL termination
To start a Nginx instance which is automatically initialized for providing SSL termination for with Apache Guacamole, including automatic retrieval of a certificate from Let's Encrypt:
some-guacamole-ssl is the name you wish to assign to your container,
some-guacamole is the hostname or IP address of your Guacamole instance or glyptodon/guacamole container,
guac.example.net is the public domain that you will use to access Guacamole over the internet, and
firstname.lastname@example.org is the email address that you wish to register with Let's Encrypt.
Supported types of SSL certificates
glyptodon/guacamole-ssl-nginx supports several mechanisms for generating, retrieving, or using existing SSL certificates. The mechanism used depends on which environment variables are specified when the Docker container is created.
In addition to these mechanism-specific environment variables, there is a set of environment variables that must always be specified:
ACCEPT_EULA- Whether you accept the Glyptodon Enterprise EULA (acceptance of the EULA is required to use the image).
GUACAMOLE_HOSTNAME- The hostname/address of the Guacamole instance.
SSL_HOSTNAME- The public domain name that will be used to access Guacamole.
Let's Encrypt is used by default if no existing certificate is supplied and generation of a self-signed certificate is not requested. The
glyptodon/guacamole-ssl-nginx image will reach out to the Let's Encrypt service using the "certbot" tool to retrieve an SSL certificate.
Only one environment variable specific to Let's Encrypt is strictly required if using Let's Encrypt certificates:
LETSENCRYPT_ACCEPT_TOS- Whether you accept the Let's Encrypt Terms of Service (acceptance of Let's Encrypt's Terms of Service is required to use that service).
In addition to accepting their Terms of Service, beware that Let's Encrypt strongly recommends providing an email address so that you can get important alerts regarding your certificate. You should additionally provide an email address unless you have a reason not to do so:
LETSENCRYPT_EMAIL- The email address to submit to Let's Encrypt when requesting the certificate.
If you are just testing usage of Let's Encrypt, you should use the Let's Encrypt staging/testing environment instead of the production environment:
LETSENCRYPT_STAGING- Set to "Y" to use Let's Encrypt's staging environment instead of production.
The retrieved certificate be automatically renewed by the image when necessary. If retrieval fails, the container will stop, details describing the failure will be logged, and the process will be retried the next time the container starts.
glyptodon/guacamole-ssl-nginx image leverages Docker volumes to enable Let's Encrypt certificates and state to persist across container recreation.
Existing certificate from an arbitrary CA
If you already have a certificate that you obtained from a certificate authority, you can use that certificate by pointing to the relevant files with the
PRIVATE_KEY_FILE environment variables. The relevant files will need to be exposed to the image using Docker volume mounts.
CERTIFICATE_FILE- The full path to the certificate PEM file.
PRIVATE_KEY_FILE- The full path to the private key PEM file.
When your certificate comes up for renewal with your CA, you will need to replace the certificate and private key and reload Nginx. Once the mounted files have been replaced, Nginx can be reloaded by sending the container process the SIGHUP signal:
If deploying for testing, the image can automatically generate and maintain its own self-signed certificate:
SELF_SIGNED- Set to "Y" to automatically generate a self-signed certificate for testing.
glyptodon/guacamole-ssl-nginx image will regenerate the self-signed certificate on startup. As the certificate expires 30 days after generation, the image will also automatically regenerate the certificate every 21 days to ensure it does not expire.
The certificate expiration date and fingerprints will be logged each time the certificate is regenerated, allowing rudimentary server identity verification.
In addition to the environment variables documented below, all environment variables supported by the official Docker Nginx image are accepted, as the official Nginx image forms the basis of this image.
ACCEPT_EULA environment variable must be set to "Y" to indicate your acceptance of the Glyptodon Enterprise EULA. This Docker image may not be used except under the terms of the EULA.
The public-facing hostname of the server hosting Docker. This environment variable is required and should be the full public domain name that will be used to access Guacamole over the internet, already associated with the IP address that reaches the server running Docker and this image.
The internal hostname or IP address of the Guacamole server. This environment variable is required, and should be the hostname/address that Nginx will connect to internally when servicing connections.
Note that the Guacamole service whose hostname/address is provided here should be reachable only on the internal network. Only the SSL terminating service (this image) should be public-facing.
The TCP port number that the Guacamole server is listening on. This environment variable is optional. If omitted, the typical port 8080 will be used by default.
The path that Guacamole is being served beneath. This environment variable is optional. By default, this will be blank, representing that Guacamole is being served from the root path. As with the
GUACAMOLE_CONTEXT_PATH environment variable of the
glyptodon/guacamole image, this parameter may not contain slashes.
For example, if Guacamole is running internally at
http://some-host/guacamole/, you would set
If set to "Y", requests that a self-signed certificate be automatically generated for
SSL_HOSTNAME rather than using an existing certificate or retrieving a new certificate from Let's Encrypt.
Self-signed certificates are inherently insecure. This option should be used only for testing.
The paths of the PEM files for the SSL certificate and associated private key, respectively. These paths are relative to the filesystem of the Docker container. Externally-provided SSL certificate PEM files will need to be exposed within the container using Docker volume mounts.
These environment variables are only required if providing your own certificate. They will be ignored if using a self-signed certificate for testing with
If intending to use Let's Encrypt, the
LETSENCRYPT_ACCEPT_TOS environment variable must be set to "Y" to indicate your acceptance of the Let's Encrypt Terms of Service. Let's Encrypt cannot be used unless you agree to the relevant Terms of Service.
This environment variable is only required if using Let's Encrypt. It is ignored if providing your own certificate using
PRIVATE_KEY_FILE, or if using a self-signed certificate for testing with
The email address that should be provided to Let's Encrypt when requesting a certificate. This environment variable is optional and is ignored if providing your own certificate using
PRIVATE_KEY_FILE, or if using a self-signed certificate for testing with
While this environment variable is optional, beware that Let's Encrypt strongly recommends providing an email address when obtaining a certificate using their service. From the help content for the certbot tool:
... This is strongly discouraged, because in the event of key loss or account compromise you will irrevocably lose access to your account. You will also be unable to receive notice about impending expiration or revocation of your certificates. Updates to the Subscriber Agreement will still affect you, and will be effective 14 days after posting an update to the web site.
If set to "Y", requests that the Let's Encrypt staging environment be used to retrieve an SSL certificate, rather than the production environment. This option should be used if you are just testing the Let's Encrypt functionality.
Rather than pass data directly in environment variables, a
_FILE suffix may be added to any environment variable supported by this image to force that variable to be read from the named file within the container. As Docker secrets store sensitive data within files beneath
/run/secrets/ within the container, this can be used to load sensitive data from Docker secrets.
For example, to load the Let's Encrypt account email from Docker secrets: