Details on how to manage addons

[wanderling]

Hello and thank you for a wonderful docker-compose setup that takes most of the guesswork out of getting a traditionally frustrating package working flawlessly and effortlessly.

I am, however, having a problem getting addons like TOTP deployed on this build. Would you mind adding documentation on how to get addons working with either the initial docker-compose or after deployment.

Thanks!

[boschkundendienst]

Hi, thanks for the positive feedback. First of all, you should not use my proof-of-concept solution in production.

Back to your question.

In detail you can find the information you need here: https://guacamole.apache.org/doc/gug/configuring-guacamole.html Take a close look at Overriding GUACAMOLE_HOME and guacamole.properties or read it completely.

What this explains is, that for any "optional_property" you have to configure them via your own guacamole.properties file. For a normal "property" you can configure them via environment variables in your docker-compose.yml.

When opening a bash shell into the guacamole docker container you can find the script /opt/guacamole/bin/start.sh. With some commands you can find out the "normal" and the "optional" properties:

find the optional ones

# this is inside the container
guacamole@82e2917562f9:/opt/guacamole$ grep -o 'set_optional_property.*\$.*' /opt/guacamole/bin/start.sh

find the normal ones

# this is inside the container
guacamole@82e2917562f9:/opt/guacamole$ grep -o 'set_property.*\$.*' /opt/guacamole/bin/start.sh

This will result in a list of lower-case upper case variable association and it shows that the builtin TOTP plugin uses "optional" properties so we have to make our own guacamole.properties file that contains values for totp-issuer, totp-digits, totp-period and totp-mode

guacamole@82e2917562f9:/opt/guacamole$ grep -o 'set_optional_property.*\$.*' /opt/guacamole/bin/start.sh | grep -i totp
set_optional_property "totp-issuer"    "$TOTP_ISSUER"
set_optional_property "totp-digits"    "$TOTP_DIGITS"
set_optional_property "totp-period"    "$TOTP_PERIOD"
set_optional_property "totp-mode"      "$TOTP_MODE"

SO DO THE FOLLOWING

1. Create the folder ./myguacamolehome/ as a subfolder relative to your docker-compose.yml file.

2. create the file ./myguacamolehome/guacamole.properties .

An example file can look like this with default settings for totp:

################################################################################
# ./myguacamolehome/guacamole.properties
################################################################################
# In previous releases, this file had to be in the classpath of your servlet
# container. Now, the location of guacamole.properties can be explicitly
# defined with environment variables or system properties, and the classpath
# is only used as a last resort. When searching for guacamole.properties,
# Guacamole will check, in order:
#  - within GUACAMOLE_HOME, as defined above.
#  - the classpath of the servlet container.
# The guacamole.properties file is optional and is used to configure
# Guacamole in situations where the defaults are insufficient, or to provide
# additional configuration information for extensions.
# See https://guacamole.apache.org/doc/gug/configuring-guacamole.html for details
################################################################################
enable-environment-properties: true
totp-issuer: "Apache Guacamole"
totp-digits: 6
totp-period: 30
totp-mode: sha1
# EVERYTHING BELOW HERE WILL BE CREATED BY
# start.sh FROM WITHIN THE GUACAMOLE CONTAINER
# add your additional properties, e.g. configuration of plugins etc. above.
################################################################################

3. add the environment variable GUACAMOLE_HOME pointing to a new folder in the container to your docker-compose.yml file and add the local ./myguacamolehome path as /myguacamolehome into the container using volumes e.g. like this:

...
    environment:
      GUACD_HOSTNAME: guacd
      POSTGRES_DATABASE: guacamole_db
      POSTGRES_HOSTNAME: postgres
      POSTGRES_PASSWORD: 'ChooseYourOwnPasswordHere1234'
      POSTGRES_USER: guacamole_user
      GUACAMOLE_HOME: /myguacamolehome
    volumes:
      - "./myguacamolehome:/myguacamolehome"
...

For example my docker-compose.yml now looks like this (GUACAMOLE_HOME and the additional volume added):

####################################################################################

version: '2.0'

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

# services
services:
  # guacd
  guacd:
    container_name: guacd_compose
    image: guacamole/guacd
    networks:
      guacnetwork_compose:
    restart: always
    volumes:
    - ./drive:/drive:rw
    - ./record:/record:rw
  # postgres
  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:13.4-buster
    networks:
      guacnetwork_compose:
    restart: always
    volumes:
    - ./init:/docker-entrypoint-initdb.d:z
    - ./data:/var/lib/postgresql/data:Z

  # guacamole
  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
      GUACAMOLE_HOME: /myguacamolehome
    image: guacamole/guacamole
    links:
    - guacd
    networks:
      guacnetwork_compose:
    volumes:
      - "./myguacamolehome:/myguacamolehome"
    ports:
## enable next line if not using nginx
##    - 8080:8080/tcp # Guacamole is on :8080/guacamole, not /.
## enable next line when using nginx
    - 8080/tcp
    restart: always

########### optional ##############
  # nginx
  nginx:
   container_name: nginx_guacamole_compose
   restart: always
   image: nginx
   volumes:
   - ./nginx/ssl/self.cert:/etc/nginx/ssl/self.cert:ro
   - ./nginx/ssl/self-ssl.key:/etc/nginx/ssl/self-ssl.key:ro
   - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
   - ./nginx/mysite.template:/etc/nginx/conf.d/default.conf:ro
   ports:
   - 8443:443
   links:
   - guacamole
   networks:
     guacnetwork_compose:
   # run nginx
   command: /bin/bash -c "nginx -g 'daemon off;'"
# nginx-debug-mode
#   command: /bin/bash -c "nginx-debug -g 'daemon off;'"
####################################################################################

Now you are able to use the TOTP plugin.

For all "normal" properties you can just use the UPPERCASE environment variables directly inside docker-compose.yml.

Do you understand what I tried to explain? Could I help you?

Regards

Peter

P.S.

A general hint from my side is to learn how to get a shell inside docker containers. It helps you to understand how they work e.g. the /opt/guacamole/bin/start.sh script and give you the necessary insides that might have been missed out in the docs.

[wanderling]

Awesome. Thanks for the pointers. I will keep them in mind as I am still about mid-way on the docker learning curve.

Another way to resolve this (I just found this in the docs), is to add the environment variable TOTP_ENABLED: 'true' to the guacamole section in your docker-compose.yml before deploying. For others reading this it will look like:

  # guacamole
  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
      GUACAMOLE_HOME: /myguacamolehome
      TOTP_ENABLED: 'true'
    image: guacamole/guacamole
    links:
    - guacd
    networks:
      guacnetwork_compose:```

[boschkundendienst]

perfect, thanks for the feedback