Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC and RDP. We call it clientless because no plugins or client software are required.
Thanks to HTML5, once Guacamole is installed on a server, all you need to access your desktops is a web browser.
Using this image will require an existing, running Docker container with the guacd image, and another Docker container providing either a PostgreSQL, MySQL or SQLServer database.
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.
Beware that 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:https://[address of container]:8080/guacamole/
. The instructions below use the
-p 8080:8080
option to expose this port at the level of the machine hosting
Docker, as well.
The string _FILE
may be appended to some of the environment variables listed
below if you are using MySQL, PostgreSQL or SQLServer authentication. This will
cause the startup script to load the values for those variables from files
within the container.
This is useful for specifying sensitive info, ie. passwords for
the database, in secured files instead of plaintext environment variables. This
is generally used for loading values from Docker secrets,
which are stored at /run/secrets/<secret_name>
within the container.
It is important to note that the startup script is configured such that:
-
You may mix the use of Docker secrets and normal environment variables. For example, you may wish to use
MYSQL_USER_FILE
andMYSQL_PASSWORD_FILE
, but wish to specify the database name withMYSQL_DATABASE
-
If both a normal environment variable and its corresponding secret are defined in the same command line, or section within a Compose file, the secret will take precedence. For instance, if both
MYSQL_PASSWORD
andMYSQL_PASSWORD_FILE
are given,MYSQL_PASSWORD_FILE
will be used.
docker run --name some-guacamole --link some-guacd:guacd \
--link some-postgres:postgres \
-e POSTGRESQL_DATABASE=guacamole_db \
-e POSTGRESQL_USER=guacamole_user \
-e POSTGRESQL_PASSWORD=some_password \
-e POSTGRESQL_DATABASE_FILE=/run/secrets/<secret_name> \
-e POSTGRESQL_USER_FILE=/run/secrets/<secret_name> \
-e POSTGRESQL_PASSWORD_FILE=/run/secrets/<secret_name> \
-d -p 8080:8080 guacamole/guacamole
Linking Guacamole to PostgreSQL requires three environment variables. If any of these environment variables are omitted, you will receive an error message, and the image will stop:
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 asPOSTGRESQL_USER
.POSTGRESQL_DATABASE_FILE
- The path of the docker secret containing the name of database to use for Guacamole authentication.POSTGRESQL_USER_FILE
- The path of the docker secret containing the name of the user that Guacamole will use to connect to PostgreSQL.POSTGRESQL_PASSWORD_FILE
- The path of the docker secret containing the password that Guacamole will provide when connecting to PostgreSQL as `POSTGRESQL_USER.
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 the Guacamole manual:
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgresql > initdb.sql
Alternatively, you can use the SQL scripts included with the guacamole-auth-jdbc extension from the corresponding release.
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
the Guacamole manual.
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 \
-e MYSQL_DATABASE_FILE=/run/secrets/<secret_name> \
-e MYSQL_USER_FILE=/run/secrets/<secret_name> \
-e MYSQL_PASSWORD_FILE=/run/secrets/<secret_name> \
-d -p 8080:8080 guacamole/guacamole
Linking Guacamole to MySQL requires three environment variables. If any of these environment variables are omitted, you will receive an error message, and the image will stop:
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 asMYSQL_USER
.MYSQL_DATABASE_FILE
- The path of the docker secret containing the name of the database to use for Guacamole authentication.MYSQL_USER_FILE
- The path of the docker secret containing the name of the user that Guacamole will use to connect to MySQL.MYSQL_PASSWORD_FILE
- The path of the docker secret containing the password that Guacamole will provide when connecting to MySQL asMYSQL_USER
.
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 the Guacamole manual:
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql
Alternatively, you can use the SQL scripts included with guacamole-auth-jdbc.
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
the Guacamole manual.
Linking Guacamole to SQLServer requires three environment variables. If any of these environment variables are omitted, you will receive an error message, and the image will stop:
-
SQLSERVER_DATABASE
- The name of the database to use for Guacamole authentication. -
SQLSERVER_USER
- The user that Guacamole will use to connect to SQLServer. -
SQLSERVER_PASSWORD
- The password that Guacamole will provide when connecting to SQLServer asSQLSERVER_USER
.docker run --name some-guacamole --link some-guacd:guacd
--link some-sqlserver:sqlserver
-e SQLSERVER_DATABASE=guacamole_db
-e SQLSERVER_USER=guacamole_user
-e SQLSERVER_PASSWORD=some_password
-d -p 8080:8080 guacamole/guacamole
Alternatively, if you want to store database credentials using Docker secrets, the following three variables are required and replace the previous three:
-
SQLSERVER_DATABASE_FILE
- The path of the docker secret containing the name of database to use for Guacamole authentication. -
SQLSERVER_USER_FILE
- The path of the docker secret containing the name of the user that Guacamole will use to connect to SQLServer. -
SQLSERVER_PASSWORD_FILE
- The path of the docker secret containing the password that Guacamole will provide when connecting to SQLServer as `SQLSERVER_USER.docker run --name some-guacamole --link some-guacd:guacd
--link some-sqlserver:sqlserver
-e SQLSERVER_DATABASE_FILE=/run/secrets/<secret_name>
-e SQLSERVER_USER_FILE=/run/secrets/<secret_name>
-e SQLSERVER_PASSWORD_FILE=/run/secrets/<secret_name>
-d -p 8080:8080 guacamole/guacamole
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 SQLServer database as documented in the Guacamole manual:
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --sqlserver > initdb.sql
Alternatively, you can use the SQL scripts included with the guacamole-auth-jdbc extension from the corresponding release.
Once this script is generated, you must:
- Create a database for Guacamole within SQLServer, such as
guacamole_db
. - Run the script on the newly-created database.
- Create a user for Guacamole within SQLServer with access to the tables and
sequences of this database, such as
guacamole_user
.
The process for doing this via the sqlcmd
utilities included
with SQLServer is documented in
the Guacamole manual.
Please report any bugs encountered by opening a new issue in our JIRA.