ra6r2015 Chapter 3. installing Guacamole with Docker Chapter 3. 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: 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 concems. 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 alll 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 stil 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 - quacd is a passive proxy and does not perform any kind of authentication. If you do not property isolate guaed 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 Fipiiguac-devergldoclgua/guacamote-docker himraer2015 Chapter 3. naling Guacamole with Docker 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. 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: 1. 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. 2. ADocker container running the mysql image. 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 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 mysql utility included with MySQL is documented in Chapter 6, Database authentication. Deploying Guacamole Linking Guacamole to MySQL will require three environment variables, These variables collectively describe how Guacamole will connect to MySQL: Variable Description Fipiiguac-devergldolgua/guacamote-docker himraer2015 Chapter 3. naling Guacamole with Docker MYSQL_DATABASE ‘The name of the database to use for Guacamole authentication, MYSQL_USER The user that Guacamole will use to connect to MySQL. The password that Guacamole will provide when connecting to MySQL as MYSQL_PASSWORD nvsol_use® ‘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=sone_password \ -d -p 8080:8080 glyptodon/guacamole 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. Vori 1g 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: 1. 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. 2. A Docker container running the postgresql image. 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 Chapter 6, Database authentication: Fipiiguac-devergldoclgua/guacamote-docker himraer2015 Chapter 3. naling Guacamole with Docker $ docker run --rm glyptodon/guacamole /opt/guacamole/bin/initdb.sh --postgresql > initab. 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 guacanole_user, The process for doing this via the psql and createdb utiities included with PostgreSQL is documented in Chapter 6, Database authentication Deploying Guacamole Linking Guacamole to your PostgreSQL database will require three 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. The password that Guacamole will provide when connecting to PostgreSQL as POSTGRES PASSWORD Pe Ere 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 \ --ink some-postgres: postgres \ ~@ POSTGRES_DATABASE-guacanole_db \ ~€ POSTGRES_USER=guacamole user — \ ~e POSTGRES_PASSWORD=some_password \ -d -p 880:8080 glyptodon/guacamole 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. 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 Fipiiguac-devergldoclgua/guacamote-docker him 45raer2015 Chapter 3. naling Guacamole with Docker 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 Fipiiguac-devergldoclgua/guacamote-docker him