Guacamole with docker-compose

This is a small documentation how to run a fully working Apache Guacamole (incubating) instance with docker (docker-compose). The goal of this project is to make it easy to test Guacamole and tunnel with cloudflared.

About Guacamole

Apache Guacamole (incubating) is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH. It is called 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.

It supports RDP, SSH, Telnet and VNC and is the fastest HTML5 gateway I know. Checkout the projects homepage for more information.

Prerequisites

You need a working docker installation and docker-compose running on your machine.

A VM or server you want a ssh tunnel to from your domain set up via cloudflared.

You need to have a domain with it's DNS routed through cloudflare. https://developers.cloudflare.com/dns/zone-setups/full-setup/setup
Follow these steps to configure your Cloudflare tuhnel and Self-Hosted Application https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/use-cases/ssh/#connect-to-ssh-server-with-cloudflared-access
Next you have to route traffic through tunnel via your domain, instructions are here:

Via public DNS records in Cloudflare https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/routing-to-tunnel/dns
via a public hostname guided by a Cloudflare Load Balancer https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/routing-to-tunnel/lb
from WARP client private traffic https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/private-net/

Quick start

Clone the GIT repository and start guacamole:

git clone "https://github.com/boschkundendienst/guacamole-docker-compose.git"
cd guacamole-docker-compose
./prepare.sh
docker-compose up -d

Your guacamole server should now be available at https://ip of your server:8443/. The default username is guacadmin with password guacadmin.

Details

To understand some details let's take a closer look at parts of the docker-compose.yml file:

Networking

The following part of docker-compose.yml will create a network with name guacnetwork_compose in mode bridged.

...
# networks
# create a network 'guacnetwork_compose' in mode 'bridged'
networks:
  guacnetwork_compose:
    driver: bridge
...

Services

guacd

The following part of docker-compose.yml will create the guacd service. guacd is the heart of Guacamole which dynamically loads support for remote desktop protocols (called "client plugins") and connects them to remote desktops based on instructions received from the web application. The container will be called guacd_compose based on the docker image guacamole/guacd connected to our previously created network guacnetwork_compose. Additionally we map the 2 local folders ./drive and ./record into the container. We can use them later to map user drives and store recordings of sessions.

...
services:
  # guacd
  guacd:
    container_name: guacd_compose
    image: guacamole/guacd
    networks:
      guacnetwork_compose:
    restart: always
    volumes:
    - ./drive:/drive:rw
    - ./record:/record:rw
...

PostgreSQL

The following part of docker-compose.yml will create an instance of PostgreSQL using the official docker image. This image is highly configurable using environment variables. It will for example initialize a database if an initialization script is found in the folder /docker-entrypoint-initdb.d within the image. Since we map the local folder ./init inside the container as docker-entrypoint-initdb.d we can initialize the database for guacamole using our own script (./init/initdb.sql). You can read more about the details of the official postgres image here.

...
  postgres:
    container_name: postgres_guacamole_compose
    environment:
      PGDATA: /var/lib/postgresql/data/guacamole
      POSTGRES_DB: guacamole_db
      POSTGRES_PASSWORD: ChooseYourOwnPasswordHere1234
      POSTGRES_USER: guacamole_user
    image: postgres
    networks:
      guacnetwork_compose:
    restart: always
    volumes:
    - ./init:/docker-entrypoint-initdb.d:ro
    - ./data:/var/lib/postgresql/data:rw
...

Guacamole

The following part of docker-compose.yml will create an instance of guacamole by using the docker image guacamole from docker hub. It is also highly configurable using environment variables. In this setup it is configured to connect to the previously created postgres instance using a username and password and the database guacamole_db. Port 8080 is only exposed locally!

...
  guacamole:
    container_name: guacamole_compose
    depends_on:
    - guacd
    - postgres
    environment:
      GUACD_HOSTNAME: guacd
      POSTGRES_DATABASE: guacamole_db
      POSTGRES_HOSTNAME: postgres
      POSTGRES_PASSWORD: ChooseYourOwnPasswordHere1234
      POSTGRES_USER: guacamole_user
    image: guacamole/guacamole
    links:
    - guacd
    networks:
      guacnetwork_compose:
    ports:
    - 8080/tcp
    restart: always
...

nginx

The following part of docker-compose.yml will create an instance of nginx that maps the public port 8443 to the internal port 443. The internal port 443 is then mapped to guacamole using the ./nginx/templates/guacamole.conf.template file. The container will use the previously generated (prepare.sh) self-signed certificate in ./nginx/ssl/ with ./nginx/ssl/self-ssl.key and ./nginx/ssl/self.cert.

We will then attach an instance of Cloudflare to nginx so it is accessible through your sub domain that was configured when setting up your cloudflare tunnel's public host.

...
  # nginx
  nginx:
   container_name: nginx_guacamole_compose
   restart: always
   image: nginx
   volumes:
   - ./nginx/templates:/etc/nginx/templates:ro
   - ./nginx/ssl/self.cert:/etc/nginx/ssl/self.cert:ro
   - ./nginx/ssl/self-ssl.key:/etc/nginx/ssl/self-ssl.key:ro
   ports:
   - 8443:443
   links:
   - guacamole
   networks:
     guacnetwork_compose:
...

Cloudflared

Creates a instance of Cloudflared that utilize the Zero Trust dashboard configuation with your TUNNEL TOKEN.

  # cloudflare
  cloudflared:
    container_name: cloudflare_gaucamole
    image: erisamoe/cloudflared
    restart: unless-stopped
    command: tunnel run
    environment:
      - TUNNEL_TOKEN=${TUNNEL_TOKEN}
    links:
      - guacamole
    networks:
     guacnetwork_compose:

prepare.sh

prepare.sh is a small script that creates ./init/initdb.sql by downloading the docker image guacamole/guacamole and start it like this:

docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgresql > ./init/initdb.sql

It creates the necessary database initialization file for postgres.

reset.sh

To reset everything to the beginning, just run ./reset.sh.

WOL

Wake on LAN (WOL) does not work and I will not fix that because it is beyound the scope of this repo. But zukkie777 who also filed this issue fixed it. You can read about it on the Guacamole mailing list

Disclaimer

Downloading and executing scripts from the internet may harm your computer. Make sure to check the source of the scripts before executing them!

shbatm / cloudflare-ssh-tunnel-guacamole-docker-compose