| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 3. Installing Guacamole with Docker</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="installing-guacamole.html" title="Chapter 2. Installing Guacamole natively" /><link rel="next" href="proxying-guacamole.html" title="Chapter 4. Proxying Guacamole" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> |
| </head><body> |
| <!-- CONTENT --> |
| |
| <div id="page"><div id="content"> |
| <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. Installing Guacamole with Docker</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="installing-guacamole.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="proxying-guacamole.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="guacamole-docker"></a>Chapter 3. Installing Guacamole with Docker</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="guacamole-docker.html#guacd-docker-image">Running the <span class="package">guacd</span> Docker image</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-docker.html#guacd-docker-guacamole">Running <span class="package">guacd</span> for use by the Guacamole Docker image</a></span></dt><dt><span class="section"><a href="guacamole-docker.html#guacd-docker-external">Running <span class="package">guacd</span> for use by services outside Docker</a></span></dt></dl></dd><dt><span class="section"><a href="guacamole-docker.html#guacamole-docker-image">The Guacamole Docker image</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-docker.html#guacamole-docker-mysql">Deploying Guacamole with MySQL authentication</a></span></dt><dt><span class="section"><a href="guacamole-docker.html#guacamole-docker-postgresql">Deploying Guacamole with PostgreSQL authentication</a></span></dt></dl></dd></dl></div><a id="idm139865879548976" class="indexterm"></a><p>Guacamole can be deployed using Docker, removing the need to build |
| <span class="package">guacamole-server</span> from source or configure the web application |
| manually. The Guacamole project provides officially-supported Docker images for both |
| Guacamole and <span class="package">guacd</span> which are kept up-to-date with each release.</p><p>A typical Docker deployment of Guacamole will involve three separate containers, linked |
| together at creation time:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="systemitem">glyptodon/guacd</code></span></dt><dd><p>Provides the <span class="package">guacd</span> daemon, built from the released |
| <span class="package">guacamole-server</span> source with support for VNC, RDP, SSH, |
| and telnet.</p></dd><dt><span class="term"><code class="systemitem">glyptodon/guacamole</code></span></dt><dd><p>Provides the Guacamole web application running within Tomcat 8 with support |
| for WebSocket. The configuration necessary to connect to the linked |
| <span class="package">guacd</span> container and MySQL or PostgreSQL database will be |
| generated automatically when the image starts.</p></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="systemitem">mysql</code> or <code class="systemitem">postgresql</code></span></dt><dd><p>Provides the database that Guacamole will use for authentication and storage |
| of connection configuration data.</p></dd></dl></div><p>This separation is important, as it facilitates upgrades and maintains proper separation |
| of concerns. With the database separate from Guacamole and <span class="package">guacd</span>, those |
| containers can be freely destroyed and recreated at will. The only container which must |
| persist data through upgrades is the database.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacd-docker-image"></a>Running the <span class="package">guacd</span> Docker image</h2></div></div></div><p>The <span class="package">guacd</span> Docker image is built from the released |
| <span class="package">guacamole-server</span> 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.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacd-docker-guacamole"></a>Running <span class="package">guacd</span> for use by the Guacamole Docker image</h3></div></div></div><p>When running the <span class="package">guacd</span> 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 <span class="package">guacd</span>.</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <span class="command"><strong>docker</strong></span> run --name <em class="replaceable"><code>some-guacd</code></em> -d glyptodon/guacd</pre></div><p>When run in this manner, <span class="package">guacd</span> will be listening on its default |
| port 4822, but this port will only be available to Docker containers that have been |
| explicitly linked to |
| <code class="varname"><em class="replaceable"><code>some-guacd</code></em></code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacd-docker-external"></a>Running <span class="package">guacd</span> for use by services outside Docker</h3></div></div></div><p>If you are not going to use the Guacamole image, you can still leverage the |
| <span class="package">guacd</span> image for ease of installation and maintenance. By |
| exposing the <span class="package">guacd</span> port, 4822, services external to Docker will |
| be able to access <span class="package">guacd</span>.</p><div class="important"><h3 class="title">Important</h3><p><span class="emphasis"><em>Take great care when doing this</em></span> - |
| <span class="package">guacd</span> is a passive proxy and does not perform any kind of |
| authentication.</p><p>If you do not properly isolate <span class="package">guacd</span> from untrusted parts |
| of your network, malicious users may be able to use <span class="package">guacd</span> as |
| a jumping point to other systems.</p></div><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <span class="command"><strong>docker</strong></span> run --name <em class="replaceable"><code>some-guacd</code></em> -d -p 4822:4822 glyptodon/guacd</pre></div><p><span class="package">guacd</span> 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 |
| <span class="package">guacd</span> directly.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacamole-docker-image"></a>The Guacamole Docker image</h2></div></div></div><p>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 <span class="package">guacd</span> |
| container and either a PostgreSQL or MySQL database, the necessary Guacamole |
| configuration will be automatically generated at startup.</p><p>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.</p><div class="important"><h3 class="title">Important</h3><p><span class="emphasis"><em>You will need to initialize the database manually</em></span>. Guacamole |
| will not automatically create its own tables, but SQL scripts are provided to do |
| this.</p></div><p>Once the Guacamole image is running, Guacamole will be accessible at |
| <code class="uri">http://<em class="replaceable"><code>HOSTNAME</code></em>:8080/guacamole/</code>, where |
| <em class="replaceable"><code>HOSTNAME</code></em> is the hostname or address of the machine |
| hosting Docker.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-docker-mysql"></a>Deploying Guacamole with MySQL authentication</h3></div></div></div><p>Before deploying Guacamole with the intent of using MySQL for authentication, |
| please ensure that you have each of the following already prepared:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>A Docker container running the <code class="systemitem">glyptodon/guacd</code> |
| image. Guacamole needs <span class="package">guacd</span> in order to function, and |
| the Guacamole Docker image depends on a linked Docker container running |
| <span class="package">guacd</span>.</p></li><li class="listitem"><p>A Docker container running the <code class="systemitem">mysql</code> |
| image.</p></li></ol></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="initializing-guacamole-docker-mysql"></a>Initializing the MySQL database</h4></div></div></div><p>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.</p><p>To generate a SQL script which can be used to initialize a fresh MySQL |
| database as documented in <a class="xref" href="jdbc-auth.html" title="Chapter 6. Database authentication">Chapter 6, <em>Database authentication</em></a>:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <span class="command"><strong>docker</strong></span> run --rm glyptodon/guacamole /opt/guacamole/bin/initdb.sh --mysql > <em class="replaceable"><code>initdb.sql</code></em></pre></div><p>Alternatively, you can use the SQL scripts included with the database |
| authentication.</p><p>Once this script is generated, you must:</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Create a database for Guacamole within MySQL, such as |
| <span class="database"><em class="replaceable"><code>guacamole_db</code></em></span>.</p></li><li class="step"><p>Create a user for Guacamole within MySQL with access to this database, |
| such as |
| <code class="systemitem"><em class="replaceable"><code>guacamole_user</code></em></code>.</p></li><li class="step"><p>Run the script on the newly-created database.</p></li></ol></div><p>The process for doing this via the <span class="command"><strong>mysql</strong></span> utility included |
| with MySQL is documented in <a class="xref" href="jdbc-auth.html" title="Chapter 6. Database authentication">Chapter 6, <em>Database authentication</em></a>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm139865879389936"></a>Deploying Guacamole</h4></div></div></div><p>Linking Guacamole to MySQL will require three environment variables. These |
| variables collectively describe how Guacamole will connect to MySQL:</p><div class="informaltable"><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody><tr><td><code class="envar">MYSQL_DATABASE</code></td><td> |
| <p>The name of the database to use for Guacamole |
| authentication.</p> |
| </td></tr><tr><td><code class="envar">MYSQL_USER</code></td><td> |
| <p>The user that Guacamole will use to connect to |
| MySQL.</p> |
| </td></tr><tr><td><code class="envar">MYSQL_PASSWORD</code></td><td> |
| <p>The password that Guacamole will provide when connecting |
| to MySQL as <code class="envar">MYSQL_USER</code>.</p> |
| </td></tr></tbody></table></div><p>Once your <span class="package">guacd</span> container is ready, and the values of the |
| above variables are known, Guacamole can be deployed through Docker:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <span class="command"><strong>docker</strong></span> run --name <em class="replaceable"><code>some-guacamole</code></em> --link <em class="replaceable"><code>some-guacd</code></em>:guacd \ |
| --link <em class="replaceable"><code>some-mysql</code></em>:mysql \ |
| -e MYSQL_DATABASE=<em class="replaceable"><code>guacamole_db</code></em> \ |
| -e MYSQL_USER=<em class="replaceable"><code>guacamole_user</code></em> \ |
| -e MYSQL_PASSWORD=<em class="replaceable"><code>some_password</code></em> \ |
| -d -p 8080:8080 glyptodon/guacamole</pre></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="verifying-guacamole-docker-mysql"></a>Verifying the Guacamole install</h4></div></div></div><p>Now that the Guacamole image is running, Guacamole should be accessible at |
| <code class="uri">http://<em class="replaceable"><code>HOSTNAME</code></em>:8080/guacamole/</code>, |
| where <em class="replaceable"><code>HOSTNAME</code></em> is the hostname or address of the |
| machine hosting Docker.</p><p>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:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <span class="command"><strong>docker</strong></span> logs <em class="replaceable"><code>some-guacamole</code></em></pre></div><p>If Guacamole has been successfully installed, you will see the Guacamole login |
| screen. The database initialization scripts will create the default |
| administrative user as "<code class="systemitem">guacadmin</code>" with the password |
| "<code class="systemitem">guacadmin</code>". <span class="emphasis"><em>You should change your |
| password immediately after verifying that your login |
| works</em></span>.</p><p>Once you have verified Guacamole has been deployed successfully, you can |
| create connections and add users through the web interface as described in <a class="xref" href="administration.html" title="Chapter 10. Administration">Chapter 10, <em>Administration</em></a>.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-docker-postgresql"></a>Deploying Guacamole with PostgreSQL authentication</h3></div></div></div><p>Before deploying Guacamole with the intent of using PostgreSQL for authentication, |
| please ensure that you have each of the following already prepared:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>A Docker container running the <code class="systemitem">glyptodon/guacd</code> |
| image. Guacamole needs <span class="package">guacd</span> in order to function, and |
| the Guacamole Docker image depends on a linked Docker container running |
| <span class="package">guacd</span>.</p></li><li class="listitem"><p>A Docker container running the <code class="systemitem">postgresql</code> |
| image.</p></li></ol></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="initializing-guacamole-docker-postgresql"></a>Initializing the PostgreSQL database</h4></div></div></div><p>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.</p><p>To generate a SQL script which can be used to initialize a fresh PostgreSQL |
| database as documented in <a class="xref" href="jdbc-auth.html" title="Chapter 6. Database authentication">Chapter 6, <em>Database authentication</em></a>:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <span class="command"><strong>docker</strong></span> run --rm glyptodon/guacamole /opt/guacamole/bin/initdb.sh --postgresql > <em class="replaceable"><code>initdb.sql</code></em></pre></div><p>Alternatively, you can use the SQL scripts included with the database |
| authentication.</p><p>Once this script is generated, you must:</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Create a database for Guacamole within PostgreSQL, such as |
| <span class="database"><em class="replaceable"><code>guacamole_db</code></em></span>.</p></li><li class="step"><p>Run the script on the newly-created database.</p></li><li class="step"><p>Create a user for Guacamole within PostgreSQL with access to the |
| tables and sequences of this database, such as |
| <code class="systemitem"><em class="replaceable"><code>guacamole_user</code></em></code>.</p></li></ol></div><p>The process for doing this via the <span class="command"><strong>psql</strong></span> and |
| <span class="command"><strong>createdb</strong></span> utilities included with PostgreSQL is documented |
| in <a class="xref" href="jdbc-auth.html" title="Chapter 6. Database authentication">Chapter 6, <em>Database authentication</em></a>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="deploying-guacamole-docker-postgresql"></a>Deploying Guacamole</h4></div></div></div><p>Linking Guacamole to your PostgreSQL database will require three environment |
| variables. These variables collectively describe how Guacamole will connect to |
| PostgreSQL:</p><div class="informaltable"><table border="1"><colgroup><col class="c1" /><col class="c2" /></colgroup><thead><tr><th>Variable</th><th>Description</th></tr></thead><tbody><tr><td><code class="envar">POSTGRES_DATABASE</code></td><td> |
| <p>The name of the database to use for Guacamole |
| authentication.</p> |
| </td></tr><tr><td><code class="envar">POSTGRES_USER</code></td><td> |
| <p>The user that Guacamole will use to connect to |
| PostgreSQL.</p> |
| </td></tr><tr><td><code class="envar">POSTGRES_PASSWORD</code></td><td> |
| <p>The password that Guacamole will provide when connecting |
| to PostgreSQL as <code class="envar">POSTGRES_USER</code>.</p> |
| </td></tr></tbody></table></div><p>Once your <span class="package">guacd</span> container is ready, and the values of the |
| above variables are known, Guacamole can be deployed through Docker:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <span class="command"><strong>docker</strong></span> run --name <em class="replaceable"><code>some-guacamole</code></em> --link <em class="replaceable"><code>some-guacd</code></em>:guacd \ |
| --link <em class="replaceable"><code>some-postgres</code></em>:postgres \ |
| -e POSTGRES_DATABASE=<em class="replaceable"><code>guacamole_db</code></em> \ |
| -e POSTGRES_USER=<em class="replaceable"><code>guacamole_user</code></em> \ |
| -e POSTGRES_PASSWORD=<em class="replaceable"><code>some_password</code></em> \ |
| -d -p 8080:8080 glyptodon/guacamole</pre></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="verifying-guacamole-docker-postgresql"></a>Verifying the Guacamole install</h4></div></div></div><p>Now that the Guacamole image is running, Guacamole should be accessible at |
| <code class="uri">http://<em class="replaceable"><code>HOSTNAME</code></em>:8080/guacamole/</code>, |
| where <em class="replaceable"><code>HOSTNAME</code></em> is the hostname or address of the |
| machine hosting Docker.</p><p>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:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <span class="command"><strong>docker</strong></span> logs <em class="replaceable"><code>some-guacamole</code></em></pre></div><p>If Guacamole has been successfully installed, you will see the Guacamole login |
| screen. The database initialization scripts will create the default |
| administrative user as "<code class="systemitem">guacadmin</code>" with the password |
| "<code class="systemitem">guacadmin</code>". <span class="emphasis"><em>You should change your |
| password immediately after verifying that your login |
| works</em></span>.</p><p>Once you have verified Guacamole has been deployed successfully, you can |
| create connections and add users through the web interface as described in <a class="xref" href="administration.html" title="Chapter 10. Administration">Chapter 10, <em>Administration</em></a>.</p></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="installing-guacamole.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="proxying-guacamole.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Installing Guacamole natively </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. Proxying Guacamole</td></tr></table></div> |
| |
| </div></div> |
| |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-75289145-1', 'auto'); |
| ga('send', 'pageview'); |
| |
| </script> |
| <!-- End Google Analytics --> |
| </body></html> |
