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:

This image is produced as part of Glyptodon Enterprise and made available under the same EULA. It is normally used to provide SSL termination for a container using the glyptodon/guacamole image.

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:

docker run --name some-guacamole-ssl \
    -e ACCEPT_EULA=Y \
    -e GUACAMOLE_HOSTNAME=some-guacamole \
    -e SSL_HOSTNAME=guac.example.net \
    -e LETSENCRYPT_ACCEPT_TOS=Y \
    -e LETSENCRYPT_EMAIL=your.email@example.net \
    -d glyptodon/guacamole-ssl-nginx

where 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 your.email@example.net is the email address that you wish to register with Let's Encrypt.

Supported types of SSL certificates

The 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

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.

The 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 CERTIFICATE_FILE and PRIVATE_KEY_FILE environment variables. The relevant files will need to be exposed to the image using Docker volume mounts.

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:

docker kill --signal=SIGHUP some-guacamole-ssl

Self-signed certificates

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.

The 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.

Environment variables

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

The 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.

SSL_HOSTNAME

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.

GUACAMOLE_HOSTNAME

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.

GUACAMOLE_PORT

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.

GUACAMOLE_CONTEXT_PATH

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 GUACAMOLE_CONTEXT_PATH to guacamole.

SELF_SIGNED

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.

CERTIFICATE_FILE and PRIVATE_KEY_FILE

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 SELF_SIGNED.

LETSENCRYPT_ACCEPT_TOS

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 CERTIFICATE_FILE and PRIVATE_KEY_FILE, or if using a self-signed certificate for testing with SELF_SIGNED.

LETSENCRYPT_EMAIL

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 CERTIFICATE_FILE and PRIVATE_KEY_FILE, or if using a self-signed certificate for testing with SELF_SIGNED.

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.

LETSENCRYPT_STAGING

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.

Docker secrets

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:

docker run --name some-guacamole-ssl \
    -e ACCEPT_EULA=Y \
    -e LETSENCRYPT_ACCEPT_TOS=Y \
    -e LETSENCRYPT_EMAIL_FILE=/run/secrets/letsencrypt-email \
    -d glyptodon/guacamole-ssl-nginx