mike-jumper commented on a change in pull request #165:
URL: https://github.com/apache/guacamole-manual/pull/165#discussion_r642642642
##########
File path: src/guacamole-docker.md
##########
@@ -0,0 +1,707 @@
+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_POST`
+: 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)=
+
+#### Optional environment variables
+
+Additional optional environment variables may be used to override Guacamole's
+default behavior with respect to concurrent connection use by one or more
+users. Concurrent use of connections and connection groups can be limited to an
+overall maximum and/or a per-user maximum:
+
+
+`MYSQL_ABSOLUTE_MAX_CONNECTIONS`
+: The absolute maximum number of concurrent connections to allow at any time,
+ regardless of the Guacamole connection or user involved. If set to "0", this
+ will be unlimited. Because this limit applies across all Guacamole
+ connections, it cannot be overridden if set.
+
+ *By default, the absolute total number of concurrent connections is unlimited
+ ("0").*
+
+`MYSQL_DEFAULT_MAX_CONNECTIONS`
+: The maximum number of concurrent connections to allow to any one Guacamole
+ connection. If set to "0", this will be unlimited. This can be overridden on
+ a per-connection basis when editing a connection.
+
+ *By default, overall concurrent use of connections is unlimited ("0").*
+
+`MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS`
+: The maximum number of concurrent connections to allow to any one Guacamole
+ connection group. If set to "0", this will be unlimited. This can be
+ overridden on a per-group basis when editing a connection group.
+
+ *By default, overall concurrent use of connection groups is unlimited ("0").*
+
+`MYSQL_DEFAULT_MAX_CONNECTIONS_PER_USER`
+: The maximum number of concurrent connections to allow a single user to
+ maintain to any one Guacamole connection. If set to "0", this will be
+ unlimited. This can be overridden on a per-connection basis when editing a
+ connection.
+
+ *By default, per-user concurrent use of connections is unlimited ("0").*
+
+`MYSQL_DEFAULT_MAX_GROUP_CONNECTIONS_PER_USER`
+: The maximum number of concurrent connections to allow a single user to
+ maintain to any one Guacamole connection group. If set to "0", this will be
+ unlimited. This can be overridden on a per-group basis when editing a
+ connection group.
+
+ *By default, per-user concurrent use of connection groups is limited to one
+ ("1")*, to prevent a balancing connection group from being completely
+ exhausted by one user alone.
+
+`MYSQL_AUTO_CREATE_ACCOUNTS`
+: Whether or not accounts that do not exist in the MySQL database will be
+ automatically created when successfully authenticated through other modules.
+ If set to "true" accounts will be automatically created. Otherwise, and by
+ default, accounts will not be automatically created and will need to be
+ manually created in order for permissions within the MySQL database extension
+ to be assigned to users authenticated with other modules.
Review comment:
Unfortunately, I don't believe so. The options seem to be:
* Document each database separately, leveraging tabs to show only the
relevant portions of the documentation.
* Document each database simultaneously, listing all applicable properties
at once regardless of which database tab is selected.
I think the tabbed approach provides the best user experience and most
readable documentation.
It's possible to leverage something like the `include` directive to include
excerpts from a file. For example, if one file contains something like:
```
+++ db-username
The username of the user that Guacamole should use to connect to the
database.
This is given as "`guacamole_user`" in the examples given in this chapter.
+++ db-password
The password Guacamole should provide when authenticating with the database.
This is given as "`some_password`" in the examples given in this chapter.
+++
```
then those bits can be included selectively with something like:
```{include} name-of-the-file.md
:start-after: +++ db-username
:end-before: +++
```
We could do that for the common properties.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
