Chapter 3. Installing Guacamole with Docker

Chapter 3. Installing Guacamole with Docker
Prev	Part I. User's Guide	Next

Chapter 3. Installing Guacamole with Docker

Table of Contents

Running the guacd Docker image

Running guacd for use by the Guacamole Docker image
Running guacd for use by services outside Docker

The Guacamole Docker image

Deploying Guacamole with MySQL authentication
Deploying Guacamole with PostgreSQL authentication

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/guacd: Provides the guacd daemon, built from the released guacamole-server source with support for VNC, RDP, SSH, and telnet.
glyptodon/guacamole: Provides 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.

mysql or postgresql: Provides 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.

Running the guacd Docker image

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.

Running guacd for use by the Guacamole Docker image

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 --name some-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.

Running guacd for use by services outside Docker

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 --name some-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

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, and need only be explicitly provided if Docker is not used to host the database.

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://HOSTNAME:8080/guacamole/, where HOSTNAME is the hostname or address of the machine hosting Docker.

Deploying Guacamole with MySQL authentication

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/guacd image. 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 mysql image, or network access to a working installation of MySQL.

Initializing the MySQL database

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_user.
Run 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.

Deploying Guacamole

Linking Guacamole to MySQL will requires additional configuration parameters specified via 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 `MYSQL_USER`.

Once your guacd container is ready, and the values of the above variables are known, Guacamole can be deployed through Docker:

$ docker run --name some-guacamole --link some-guacd:guacd \
    --link some-mysql:mysql         \
    -e MYSQL_DATABASE=guacamole_db  \
    -e MYSQL_USER=guacamole_user    \
    -e MYSQL_PASSWORD=some_password \
    -d -p 8080:8080 glyptodon/guacamole

The network connection information for MySQL is normally implied through the "mysql" Docker link, and thus does not need to be explicitly specified. If you are not using Docker to provide your MySQL database, you will need to provide the network connection information yourself using additional environment variables:

Variable	Description
`MYSQL_HOSTNAME`	The hostname of the database to use for Guacamole authentication. This is required if you are not using Docker to provide your MySQL database.
`MYSQL_PORT`	The user that Guacamole will use to connect to MySQL. This environment variable is optional. If not provided, the standard MySQL port of 3306 will be used.

The MYSQL_HOSTNAME and, if necessary, MYSQL_POST environment variables can thus be used in place of a Docker link if using a Docker link is impossible or undesirable:

$ docker run --name some-guacamole --link some-guacd:guacd \
    -e MYSQL_HOSTNAME=172.17.42.1   \
    -e MYSQL_DATABASE=guacamole_db  \
    -e MYSQL_USER=guacamole_user    \
    -e MYSQL_PASSWORD=some_password \
    -d -p 8080:8080 glyptodon/guacamole

If any required environment variables are omitted, you will receive an error message in the logs, and the image will stop. You will then need to recreate the container with the proper variables specified.

Verifying the Guacamole install

Now that the Guacamole image is running, Guacamole should be accessible at http://HOSTNAME:8080/guacamole/, where 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 logs some-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.

Deploying Guacamole with PostgreSQL authentication

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/guacd image. 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 postgresql image, or network access to a working installation of PostgreSQL.

Initializing the PostgreSQL database

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

Deploying Guacamole

Linking Guacamole to your PostgreSQL database will require additional configuration parameters specified via 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 `POSTGRES_USER`.

Once your guacd container is ready, and the values of the above variables are known, Guacamole can be deployed through Docker:

$ docker run --name some-guacamole --link some-guacd:guacd \
    --link some-postgres:postgres      \
    -e POSTGRES_DATABASE=guacamole_db  \
    -e POSTGRES_USER=guacamole_user    \
    -e POSTGRES_PASSWORD=some_password \
    -d -p 8080:8080 glyptodon/guacamole

The network connection information for PostgreSQL is normally implied through the "postgres" Docker link, and thus does not need to be explicitly specified. If you are not using Docker to provide your PostgreSQL database, you will need to provide the network connection information yourself using additional environment variables:

Variable	Description
`POSTGRES_HOSTNAME`	The hostname of the database to use for Guacamole authentication. This is required if you are not using Docker to provide your PostgreSQL database.
`POSTGRES_PORT`	The user that Guacamole will use to connect to PostgreSQL. This environment variable is optional. If not provided, the standard PostgreSQL port of 5432 will be used.

The POSTGRES_HOSTNAME and, if necessary, POSTGRES_POST environment variables can thus be used in place of a Docker link if using a Docker link is impossible or undesirable:

$ docker run --name some-guacamole --link some-guacd:guacd \
    -e POSTGRES_HOSTNAME=172.17.42.1   \
    -e POSTGRES_DATABASE=guacamole_db  \
    -e POSTGRES_USER=guacamole_user    \
    -e POSTGRES_PASSWORD=some_password \
    -d -p 8080:8080 glyptodon/guacamole

Verifying the Guacamole install

Now that the Guacamole image is running, Guacamole should be accessible at http://HOSTNAME:8080/guacamole/, where HOSTNAME is the hostname or address of the machine hosting Docker.

$ docker logs some-guacamole

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.

Prev	Up	Next
Chapter 2. Installing Guacamole natively	Home	Chapter 4. Proxying Guacamole