Docker deployment of NGINX for SSL termination with Keeper Connection Manager
Image: keeper/guacamole-ssl-nginx
keeper/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 Keeper Connection Manager and made available under the same EULA. It is normally used to provide SSL termination for a container using the keeper/guacamole image.

Supported types of SSL certificates

The keeper/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 Keeper Connection Manager 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 keeper/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 keeper/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.
  • 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. Stop and start the Docker Compose after the certificate has been updated.
For Docker Compose configuration, the example below will load a custom certificate from a shared volume that will hold the keys.
image: keeper/guacamole-ssl-nginx:2
restart: unless-stopped
- "80:80"
- "443:443"
CERTIFICATE_FILE: "/path/in/container/mycert.pem"
PRIVATE_KEY_FILE: "/path/in/container/mykey.pem"
- "/local/path/to/keys:/path/in/container/"

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 keeper/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.


The ACCEPT_EULA environment variable must be set to "Y" to indicate your acceptance of the Keeper Connection Manager 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 keeper/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.


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


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.


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.


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 LETSENCRYPT_EMAIL_FILE=/run/secrets/letsencrypt-email \
-d keeper/guacamole-ssl-nginx