Table of Contents
Guacamole can be deployed using Docker, removing the need to build guacamole-server from source or configure the web application manually. The Guacamole project provides officially-supported Docker images for both Guacamole and guacd which are kept up-to-date with each release.
A typical Docker deployment of Guacamole will involve three separate containers, linked together at creation time:
glyptodon/guacdProvides the guacd daemon, built from the released guacamole-server source with support for VNC, RDP, SSH, and telnet.
glyptodon/guacamoleProvides the Guacamole web application running within Tomcat 8 with support for WebSocket. The configuration necessary to connect to the linked guacd container and MySQL or PostgreSQL database will be generated automatically when the image starts.
mysqlorpostgresqlProvides the database that Guacamole will use for authentication and storage of connection configuration data.
This separation is important, as it facilitates upgrades and maintains proper separation of concerns. With the database separate from Guacamole and guacd, those containers can be freely destroyed and recreated at will. The only container which must persist data through upgrades is the database.
The guacd Docker image is built from the released guacamole-server source with support for VNC, RDP, SSH, and telnet. Common pitfalls like installing the required dependencies, installing fonts for SSH or telnet, and ensuring the FreeRDP plugins are installed to the correct location are all taken care of. It will simply just work.
When running the guacd image with the intent of linking to a Guacamole container, no ports need be exposed on the network. Access to these ports will be handled automatically by Docker during linking, and the Guacamole image will properly detect and configure the connection to guacd.
$docker run --namesome-guacd-d glyptodon/guacd
When run in this manner, guacd will be listening on its default
port 4822, but this port will only be available to Docker containers that have been
explicitly linked to
some-guacd
If you are not going to use the Guacamole image, you can still leverage the guacd image for ease of installation and maintenance. By exposing the guacd port, 4822, services external to Docker will be able to access guacd.
Important
Take great care when doing this - guacd is a passive proxy and does not perform any kind of authentication.
If you do not properly isolate guacd from untrusted parts of your network, malicious users may be able to use guacd as a jumping point to other systems.
$docker run --namesome-guacd-d -p 4822:4822 glyptodon/guacd
guacd will now be listening on port 4822, and Docker will expose this port on the same server hosting Docker. Other services, such as an instance of Tomcat running outside of Docker, will be able to connect to guacd directly.
The Guacamole Docker image is built on top of a standard Tomcat 8 image and takes care of all configuration automatically. When properly linked to a guacd container and either a PostgreSQL or MySQL database, the necessary Guacamole configuration will be automatically generated at startup.
The name of the database and all associated credentials are specified with environment variables given when the container is created. All other configuration information is generated from the Docker links.
Important
You will need to initialize the database manually. Guacamole will not automatically create its own tables, but SQL scripts are provided to do this.
Once the Guacamole image is running, Guacamole will be accessible at
http://, where
HOSTNAME:8080/guacamole/HOSTNAME is the hostname or address of the machine
hosting Docker.
Before deploying Guacamole with the intent of using MySQL for authentication, please ensure that you have each of the following already prepared:
A Docker container running the
glyptodon/guacdimage. Guacamole needs guacd in order to function, and the Guacamole Docker image depends on a linked Docker container running guacd.A Docker container running the
mysqlimage.
If your database is not already initialized with the Guacamole schema, you will need to do so prior to using Guacamole. A convenience script for generating the necessary SQL to do this is included in the Guacamole image.
To generate a SQL script which can be used to initialize a fresh MySQL database as documented in Chapter 6, Database authentication:
$docker run --rm glyptodon/guacamole /opt/guacamole/bin/initdb.sh --mysql >initdb.sql
Alternatively, you can use the SQL scripts included with the database authentication.
Once this script is generated, you must:
Create a database for Guacamole within MySQL, such as
guacamole_db.Create a user for Guacamole within MySQL with access to this database, such as
guacamole_userRun the script on the newly-created database.
The process for doing this via the mysql utility included with MySQL is documented in Chapter 6, Database authentication.
Linking Guacamole to MySQL will require three environment variables. These variables collectively describe how Guacamole will connect to MySQL:
| Variable | Description |
|---|---|
MYSQL_DATABASE |
The name of the database to use for Guacamole authentication. |
MYSQL_USER |
The user that Guacamole will use to connect to MySQL. |
MYSQL_PASSWORD |
The password that Guacamole will provide when connecting
to MySQL as |
Once your guacd container is ready, and the values of the above variables are known, Guacamole can be deployed through Docker:
$docker run --namesome-guacamole--linksome-guacd:guacd \ --linksome-mysql:mysql \ -e MYSQL_DATABASE=guacamole_db\ -e MYSQL_USER=guacamole_user\ -e MYSQL_PASSWORD=some_password\ -d -p 8080:8080 glyptodon/guacamole
If any of the configuration environment variables are omitted, you will receive an error message, and the image will stop. You will then need to recreate the container with the proper variables specified.
Now that the Guacamole image is running, Guacamole should be accessible at
http://,
where HOSTNAME:8080/guacamole/HOSTNAME is the hostname or address of the
machine hosting Docker.
If you cannot access Guacamole, check the logs using Docker to determine if something is wrong. Configuration parameters may have been given incorrectly, or the database may be improperly initialized:
$docker logssome-guacamole
If Guacamole has been successfully installed, you will see the Guacamole login
screen. The database initialization scripts will create the default
administrative user as "guacadmin" with the password
"guacadmin". You should change your
password immediately after verifying that your login
works.
Once you have verified Guacamole has been deployed successfully, you can create connections and add users through the web interface as described in Chapter 10, Administration.
Before deploying Guacamole with the intent of using PostgreSQL for authentication, please ensure that you have each of the following already prepared:
A Docker container running the
glyptodon/guacdimage. Guacamole needs guacd in order to function, and the Guacamole Docker image depends on a linked Docker container running guacd.A Docker container running the
postgresqlimage.
If your database is not already initialized with the Guacamole schema, you will need to do so prior to using Guacamole. A convenience script for generating the necessary SQL to do this is included in the Guacamole image.
To generate a SQL script which can be used to initialize a fresh PostgreSQL database as documented in Chapter 6, Database authentication:
$docker run --rm glyptodon/guacamole /opt/guacamole/bin/initdb.sh --postgresql >initdb.sql
Alternatively, you can use the SQL scripts included with the database authentication.
Once this script is generated, you must:
Create a database for Guacamole within PostgreSQL, such as
guacamole_db.Run the script on the newly-created database.
Create a user for Guacamole within PostgreSQL with access to the tables and sequences of this database, such as
guacamole_user
The process for doing this via the psql and createdb utilities included with PostgreSQL is documented in Chapter 6, Database authentication.
Linking Guacamole to your PostgreSQL database will require three environment variables. These variables collectively describe how Guacamole will connect to PostgreSQL:
| Variable | Description |
|---|---|
POSTGRES_DATABASE |
The name of the database to use for Guacamole authentication. |
POSTGRES_USER |
The user that Guacamole will use to connect to PostgreSQL. |
POSTGRES_PASSWORD |
The password that Guacamole will provide when connecting
to PostgreSQL as |
Once your guacd container is ready, and the values of the above variables are known, Guacamole can be deployed through Docker:
$docker run --namesome-guacamole--linksome-guacd:guacd \ --linksome-postgres:postgres \ -e POSTGRES_DATABASE=guacamole_db\ -e POSTGRES_USER=guacamole_user\ -e POSTGRES_PASSWORD=some_password\ -d -p 8080:8080 glyptodon/guacamole
If any of the configuration environment variables are omitted, you will receive an error message, and the image will stop. You will then need to recreate the container with the proper variables specified.
Now that the Guacamole image is running, Guacamole should be accessible at
http://,
where HOSTNAME:8080/guacamole/HOSTNAME is the hostname or address of the
machine hosting Docker.
If you cannot access Guacamole, check the logs using Docker to determine if something is wrong. Configuration parameters may have been given incorrectly, or the database may be improperly initialized:
$docker logssome-guacamole
If Guacamole has been successfully installed, you will see the Guacamole login
screen. The database initialization scripts will create the default
administrative user as "guacadmin" with the password
"guacadmin". You should change your
password immediately after verifying that your login
works.
Once you have verified Guacamole has been deployed successfully, you can create connections and add users through the web interface as described in Chapter 10, Administration.