the_information_nexus/random/guacamole_docker.md

# Installing Guacamole with Docker

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:

`guacamole/guacd`
: Provides the guacd daemon, built from the released guacamole-server source
with support for VNC, RDP, SSH, telnet, and Kubernetes.

`guacamole/guacamole`
: Provides the Guacamole web application running within Tomcat 8 with support
for WebSocket. The configuration necessary to connect to guacd, MySQL,
PostgreSQL, LDAP, etc. will be generated automatically when the image starts
based on Docker links or environment variables.

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

(guacd-docker-image)=

## Running the guacd Docker image

The guacd Docker image is built from the released guacamole-server source with
support for VNC, RDP, SSH, telnet, and Kubernetes. Common pitfalls like
installing the required dependencies, installing fonts for SSH, telnet, or
Kubernetes, and ensuring the FreeRDP plugins are installed to the correct
location are all taken care of. It will simply just work.

(guacd-docker-guacamole)=

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

```console
$ docker run --name some-guacd -d guacamole/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`.

The log level of guacd can be controlled with the `GUACD_LOG_LEVEL` environment
variable. The default value is `info`, and can be set to any of the valid
settings for the guacd log flag (-L).

```console
$ docker run -e GUACD_LOG_LEVEL=debug -d guacamole/guacd
```

(guacd-docker-external)=

### 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.
:::

```console
$ docker run --name some-guacd -d -p 4822:4822 guacamole/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.

(guacamole-docker-image)=

## 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. The configuration information
required for guacd and the various authentication mechanisms are specified with
environment variables or Docker links given when the container is created.

:::{important}
If using [PostgreSQL](guacamole-docker-postgresql) or [MySQL](guacamole-docker-mysql)
for authentication, _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
{samp}`http://{HOSTNAME}:8080/guacamole/`, where `HOSTNAME` is the hostname or
address of the machine hosting Docker.

(guacamole-docker-config-via-env)=

### Configuring Guacamole when using Docker

When running Guacamole using Docker, the traditional approach to configuring
Guacamole by editing `guacamole.properties` is less convenient. When using
Docker, you may wish to make use of the `enable-environment-properties`
configuration property, which allows you to specify values for arbitrary
Guacamole configuration properties using environment variables. This is covered
in [](configuring-guacamole).

(guacamole-docker-guacd)=

### Connecting Guacamole to guacd

The Guacamole Docker image needs to be able to connect to guacd to establish
remote desktop connections, just like any other Guacamole deployment. The
connection information needed by Guacamole will be provided either via a Docker
link or through environment variables.

If you will be using Docker to provide guacd, and you wish to use a Docker link
to connect the Guacamole image to guacd, the connection details are implied by
the Docker link:

```console
$ docker run --name some-guacamole \
    --link some-guacd:guacd        \
    ...
    -d -p 8080:8080 guacamole/guacamole
```

If you are not using Docker to provide guacd, you will need to provide the
network connection information yourself using additional environment variables:

`GUACD_HOSTNAME`
: The hostname of the guacd instance to use to establish remote desktop
connections. _This is required if you are not using Docker to provide guacd._

`GUACD_PORT`
: The port that Guacamole should use when connecting to guacd. This environment
variable is optional. If not provided, the standard guacd port of 4822 will
be used.

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

```console
$ docker run --name some-guacamole \
    -e GUACD_HOSTNAME=172.17.42.1  \
    -e GUACD_PORT=4822             \
    ...
    -d -p 8080:8080 guacamole/guacamole
```

_A connection to guacd is not the only thing required for Guacamole to work_;
some authentication mechanism needs to be configured, as well.
[MySQL](guacamole-docker-mysql), [PostgreSQL](guacamole-docker-postgresql), and
[LDAP](guacamole-docker-ldap) are supported for this, and are described in more
detail in the sections below. If the required configuration options for at
least one authentication mechanism are not provided, the Guacamole image will
not be able to start up, and you will see an error.

(guacamole-docker-mysql)=

### MySQL authentication

To use Guacamole with the MySQL authentication backend, you will need either a
Docker container running the `mysql` image, or network access to a working
installation of MySQL. The connection to MySQL can be specified using either
environment variables or a Docker link.

(initializing-guacamole-docker-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 [](jdbc-auth):

```console
$ docker run --rm guacamole/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:

1. Create a database for Guacamole within MySQL, such as `guacamole_db`.

2. Create a user for Guacamole within MySQL with access to this database, such
   as `guacamole_user`.

3. Run the script on the newly-created database.

The process for doing this via the {command}`mysql` utility included with MySQL
is documented [](jdbc-auth).

(guacamole-docker-mysql-connecting)=

#### Connecting Guacamole to MySQL

If your MySQL database is provided by another Docker container, and you wish to
use a Docker link to connect the Guacamole image to your database, the
connection details are implied by the Docker link itself:

```console
$ docker run --name some-guacamole \
    --link some-guacd:guacd        \
    --link some-mysql:mysql        \
    ...
    -d -p 8080:8080 guacamole/guacamole
```

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:

`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 port that Guacamole should use when connecting 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_PORT` environment variables can
thus be used in place of a Docker link if using a Docker link is impossible or
undesirable:

```console
$ docker run --name some-guacamole \
    --link some-guacd:guacd        \
    -e MYSQL_HOSTNAME=172.17.42.1  \
    ...
    -d -p 8080:8080 guacamole/guacamole
```

Note that a Docker link to guacd (the `--link some-guacd:guacd` option above)
is not required any more than a Docker link is required for MySQL. The
connection information for guacd can be specified using environment variables,
as described in [](guacamole-docker-guacd).

(guacamole-docker-mysql-required-vars)=

#### Required environment variables

Using MySQL for authentication requires additional configuration parameters
specified via environment variables. These variables collectively describe how
Guacamole will connect to MySQL:

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

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.

(guacamole-docker-mysql-optional-vars)=

(guacamole-docker-postgresql)=

### PostgreSQL authentication

To use Guacamole with the PostgreSQL authentication backend, you will
need either a Docker container running the `postgres` image, or
network access to a working installation of PostgreSQL. The connection
to PostgreSQL can be specified using either environment variables or a
Docker link.

(initializing-guacamole-docker-postgresql)=

#### Initializing the PostgreSQL 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 PostgreSQL
database as documented in [](jdbc-auth):

```console
$ docker run --rm guacamole/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:

1. Create a database for Guacamole within PostgreSQL, such as
   `guacamole_db`.

2. Run the script on the newly-created database.

3. 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 {command}`psql` and {command}`createdb`
utilities included with PostgreSQL is documented in [](jdbc-auth).

(guacamole-docker-postgresql-connecting)=

#### Connecting Guacamole to PostgreSQL

If your PostgreSQL database is provided by another Docker container, and you
wish to use a Docker link to connect the Guacamole image to your database, the
connection details are implied by the Docker link itself:

```console
$ docker run --name some-guacamole \
    --link some-guacd:guacd        \
    --link some-postgres:postgres  \
    ...
    -d -p 8080:8080 guacamole/guacamole
```

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:

`POSTGRESQL_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._

`POSTGRESQL_PORT`
: The port that Guacamole should use when connecting to PostgreSQL. This
environment variable is optional. If not provided, the standard PostgreSQL
port of 5432 will be used.

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

```console
$ docker run --name some-guacamole     \
    --link some-guacd:guacd            \
    -e POSTGRESQL_HOSTNAME=172.17.42.1 \
    ...
    -d -p 8080:8080 guacamole/guacamole
```

Note that a Docker link to guacd (the `--link some-guacd:guacd` option above)
is not required any more than a Docker link is required for PostgreSQL. The
connection information for guacd can be specified using environment variables,
as described in [](guacamole-docker-guacd).

(guacamole-docker-postgresql-required-vars)=

#### Required environment variables

Using PostgreSQL for authentication requires additional configuration
parameters specified via environment variables. These variables collectively
describe how Guacamole will connect to PostgreSQL:

`POSTGRESQL_DATABASE`
: The name of the database to use for Guacamole authentication.

`POSTGRESQL_USER`
: The user that Guacamole will use to connect to PostgreSQL.

`POSTGRESQL_PASSWORD`
: The password that Guacamole will provide when connecting to PostgreSQL as
`POSTGRESQL_USER`.

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.

(guacamole-docker-postgresql-optional-vars)=

### Verifying the Guacamole install

Once the Guacamole image is running, Guacamole should be accessible at
{samp}`http://{HOSTNAME}:8080/guacamole/`, where `HOSTNAME` is the hostname or
address of the machine hosting Docker, and you _should_ see a login screen. If
using MySQL or PostgreSQL, the database initialization scripts will have
created a default administrative user called "`guacadmin`" with the password
"`guacadmin`". _You should log in and change your password immediately._ If
using LDAP, you should be able to log in as any valid user within your LDAP
directory.

If you cannot access Guacamole, or you do not see a login screen, check
Docker's logs using the `docker logs` command to determine if something is
wrong. Configuration parameters may have been given incorrectly, or the
database may be improperly initialized:

```console
$ docker logs some-guacamole
```