Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, SSH, and Telnet. This docker primarily has a MariaDB (MySQL) database built-in for authentication and configuration. It also has support for external database server (mysql, sqlserver or postgresql) and authentication providers: ldap, duo, totp, cas, openid, saml, ssl, json, header, quickconnect. Thanks to HTML5, once Guacamole is installed on a server, all you need to access your desktops is a web browser.

For general usage of Apache Guacamole the full manual is located here: https://guacamole.apache.org/doc/gug/⁠

The project is based on the work of Zuhkov [email protected]⁠⁠, aptalca and Jason Bean, updated by cleao to latest version of guacamole.

All the required configuration for the authentication methods is provided by the template/environment variables. Internal MariaDB is the default authentication and configuration method if no external database server is specifyed in the EXTENSION_PRIORITY environment variable. You can add additional configuration editing guacamole config file (/config/guacamole/guacamole.properties) but don't change the required parameters (see in manual) for authentication, they are automaticly filled by the docker template options/environment variables.

If using an external database server (Mysql/MariaDB, Postgresql or MSSQLserver) you must provide it with guacamole schema and an user, more info: https://guacamole.apache.org/doc/gug/jdbc-auth.html⁠ In the option EXTENSION_PRIORITY you can add comma-separated list of external database server (mysql, sqlserver or postgresql) and authentication providers (ldap, duo, totp, cas, openid, saml, ssl, json, header, quickconnect) that should be acessed in specific order (don't specify "*" here) - INTERNAL (MariaDB) IS USED IF ANY DATABASE SERVER IS SPECIFYED! All other options are self explained or you can use the manual located here: https://guacamole.apache.org/doc/gug⁠

Docker run example: docker run -d --name='Guacamole' --net='bridge' -e 'EXTENSION_PRIORITY'='' -e 'PUID'='99' -e 'PGID'='100' -p '8080:8080/tcp' -v 'watheverpathyouwant':'/config':'rw' 'cleao/guacamole'

Session recordings when properly configured in GUI will be stored in the configurable Environment Path to be accessible outside docker. Once the Guacamole image is running, will be accessible at: http://your-host-ip:8080⁠ and login with user and password: guacadmin

Apache Guacamole copyright The Apache Software Foundation, Licenced under the Apache License, Version 9

..................

Environment variables:

EXTENSION_PRIORITY: Comma-separated list of external database server (mysql, sqlserver or postgresql) and authentication providers (ldap, duo, totp, cas, openid, saml, ssl, json, header, quickconnect) that should be acessed in specific order. Use internal (MariaDB) if any external database chosen,

DATABASE_HOSTNAME: External database server name or IP adress:port,

DATABASE_NAME: External database name,

DATABASE_USERNAME: External database user name,

DATABASE_PASSWORD: External database password,

LDAP_HOSTNAME: External LDAP server name or IP adress, and port,

LDAP_USER_BASE_DN: External LDAP user base dn,

DUO_API_HOSTNAME: External duo api hostname,

DUO_CLIENT_ID: External duo client id,

DUO_CLIENT_SECRET: External duo client secret,

DUO_REDIRECT_URI: External duo client uri,

CAS_AUTHORIZATION_ENDPOINT: CAS authorization endpoint,

CAS_REDIRECT_URI: CAS redirect uri,

OPENID_AUTHORIZATION_ENDPOINT: OPENID authorization endpoint,

OPENID_JWKS_ENDPOINT: OPENID jwks endpoint,

OPENID_ISSUER: OPENID issuer,

OPENID_CLIENT_ID: OPENID client id,

OPENID_REDIRECT_URI: OPENID redirect uri,

SSL_AUTH_URI: SSL auth uri,

SSL_AUTH_PRIMARY_URI: SSL auth primary uri,

JSON_SECRET_KEY: JSON secret key

Container Path: /config: AppData Config Path

Container Path: /var/lib/guacamole/recordings

Internal port: 8080

Edited October 28, 2025Oct 28 by Cabé
Update to v1.0.3 of the application

Hello,

thank's for your job and your share.

I was using cleao/guacamole with openid, all was working fine.

This morning, after your last update, openid was down.

I searched the forum and found this post.

This is my issues:

So in my template I added :

'EXTENSION_PRIORITY'='openid,*'

Saddly, not working. I noticed 2 new lines in guacamole.properties :

extension-priority: mysql,openid,*

extension-priority: mysql,openid,*

The order is bad, because openid must be set in first position.

So I changed to:

'EXTENSION_PRIORITY'='openid,mysql,*'

this time it's ok, except always 2 lines added instead of 1 in guacamole.properties :

extension-priority: openid,mysql,*

extension-priority: openid,mysql,*

OpenId connect is working, but, the bad news, is that all my previous settings of apache guacamole are gone

If I connect with openid and my previous settings, I have not admin right.

So I remove openid, and I connect with user/password: guacadmin

And with this method I have admin rights, but I lost all my apache guacamole settings.

It's like a fresh apache guacamole install.

I tried to describe the best I can this issue. Tell me if you need more informations.

My be there's someting I'm doing wrong ?

Can you help me to recover my previous apache guacamole settings, I dont want to start with a fresh install and reconfigure all.

Thank's

Hello, Nonoss

Thank's for using my container,

The option EXTENSION_PRIORITY like I said in the first post "you can add comma-separated list of external database server (mysql, sqlserver or postgresql) and authentication providers (ldap, duo, totp, cas, openid, saml, ssl, json, header, quickconnect) that should be acessed in specific order. Use internal (MariaDB) if any external database chosen. Ex: mysql,ldap" - Thath means if you don't specify any database server than the internal will be used (data is in /config/databases of the container)

Pheraps you where using the internal database, than you must fill this option with just: openid,* and remove the line you added in guacamole.properties because it's automaticly filled

For the previous settings, if you ever specify one external database server (mysql, sqlserver or postgresql) in the option EXTENSION_PRIORITY than the internal data is removed and the solution is to recover the path declared in the option AppData Config Path from backup or reconfigure all

Thank's @Cabé for your quick reply and help.

I always used the internal database

This is what I did after your reply:

• I deleted may apache guacamole appdata.

• Resored the backup I made just before the update.

• Configured the template with : EXTENSION_PRIORITY=openid,*

• Started the container

• Stopped the container

• Deleted the 2 new lines in guacamole.properties

• Started the container

And All is working, my apache guacamole config is back, with openid, Hourra!

I must have done some errors when I tried multiple parameters.

Thank's again and sorry for the disturb.

PS : I never added manually the 2 lines :

extension-priority: mysql,openid,*

extension-priority: mysql,openid,*

They were added automatically when the container start

Edited October 3, 2025Oct 3 by Nonoss

Glad i'ts working!

You don't disturb 😀 I'm doing the best I can with pleasure, it's the first release and after some tests there is allways something to update

With your help I will launch v1.0.1 today with some corrections like: never delete the internal database in any situation and don't need the '*' in the EXTENSION_PRIORITY , ',mysql' will be added in last

may a question @Cabé

as mine went offline with a error

now i saw you changed something, when reading, seems i missunderstand something

i added a Variable

what i still see, my .prop file is always rewritten to localhost and doesnt keep the ip from the mariadb

seems i miss something ;)

Hello altruismo, thank's for using my contentor,

For wath i see you use an existing template and pheraps an existing exported path from other guacamole app.

You must remove the app (the image must be deleted) and add it again from community apps, atention to the hidden option: AppData Config Path , you are using an external database (declaring mysql in option: EXTENSION_PRIORITY) please confirm that the path does not exist.

Dont forget to fill the options for access the external database.

This confirm a new deploy, because i see in your post the template is not the last nor the file guacamole.properties is not the one deployed with the app

Edited October 4, 2025Oct 4 by Cabé

6 hours ago, Cabé said:

Hello altruismo, thank's for using my contentor,

thanks to you for providing the "all in one" and continue the project 👍

and yes, all back again with all existing data when reading properly ... my fault ;)

thanks

Release 1.0.3 of project out.

Code changes , latest Guac docker build (1.6.0) , Tomcat 9, java connector's: mysql:9.5.0 , potgresql:42.7.8 , mssql:13.2.1

The template is changed to v1.0.3

Perhaps it's me, but it doesn't appear that the TOTP extension is working.

I've toggled the deployment to Y, however I'm never prompted to add a TOTP code; nothing happens. This is different from the older Guacamole app from jasonbean, where a TOTP prompt is seen once a user logs in for the first time.

Am I missing something?

Hello Cambelot, pheraps you are using the template from jasonbean, add the application and give it other name, i think it will pull the correct template, then it's not an Y , its the word totp in the correct variable

I'm a newbie and trying to figure out how to use guacamole - i have xrdp running on a linux host and I can connect no problem from my local computer.

Where I think I'm stuck is creating a connection in guac. What should the hostname for guacd be? I tried localhost, 127.0.0.1 with port 8801/4822 - no luck yet.

Hello Austin, this docker includes the server (guacd) and client (guacamole) incorporated, inclusively an database server (mariadb) to , just to simplify. The only parameters you need are the required: port (web gui) and the hidden: path, nothing more. If the connection you are talking is inside the running guacamole, than the ip and connection port is the same in the rdp client you use in your local computer

See: https://guacamole.apache.org/doc/1.6.0/gug/using-guacamole.html

Edited November 9, 2025Nov 9 by Cabé

Hi @Cabé , hi everyone,

Thanks for the unraid docker image.

I setup mine with external postgreSQL server. When you want to do this also, remember to place the following jar-library to the lib folder:

wget https://jdbc.postgresql.org/download/postgresql-42.7.10.jar

Hi enabler, thanks for use unraid docker image and for the feedback, if you use an external postgres database you don’t need to manualy place the jar-library to the lib folder, just write 'postgresql' in the variable: External authentication provider(s) and restart the aplication and the file will be automatically in the lib folder (it's not the last version but tomorrow i'l release a new version with last updates) you can confirm in the log

Hi Cabé,

I am wondering if the internal guacd supports VNC connections to Mac OS with password only. Where can I check if that is present or which log shows me what could be wrong?

If vnc client can, you can with guacd , but i can't help you with that, logs inside the contentor, check apache Guacamole doc's...

Ok i figured it out: you can now use the user/pass combination of your mac user instead of the legacy vnc password. iIt is also described in a bug report: https://issues.apache.org/jira/browse/GUACAMOLE-1133

Hi @Cabé ,

The latest update to 1.0.4 bricked the functionality with postgreSQL. Reason is that the lib folder is now empty and no file for postgresql exist: https://jdbc.postgresql.org/download/postgresql-42.7.10.jar

You might remember that I stored this file manually and you suggested to put postgresql to my extension-priority. I did already do that before running the upgrade. My guacamole.properties file looks as follows:

guacd-hostname: localhost
guacd-port:     4822
extension-priority: postgresql, openid
postgresql-hostname: 192.168.20.54
postgresql-port: 5432
postgresql-database: <db details hidden>
postgresql-username: <db details hidden>
postgresql-password: <db details hidden>

openid-authorization-endpoint: <id details hidden>
openid-jwks-endpoint: <id details hidden>
openid-issuer: <id details hidden>
openid-client-id: <id details hidden>
openid-redirect-uri: <id details hidden>

I think there is a bug which does not put the latest postgresql jar file to the lib folder. Maybe you know how to fix it.

I can't reproduce your problem, you say there is no postresql-42.7.10.jar file in /config/guacamole/lib of the docker?

Try to change 'AppData Config Path' (edit docker and Show more settings)

Yes, after upgrading to latest docker image I did see no postgresql*.jar file anymore in /config/guacamole/lib folder. I did not change any settings. I am using the following environment, path settings:

OPENID_AUTHORIZATION_ENDPOINT=<removed>
OPENID_REDIRECT_URI=<removed>
JSON_SECRET_KEY=<removed>
DATABASE_NAME=guacamole
DATABASE_PASSWORD=<removed>
DATABASE_HOSTNAME=192.168.20.54:5432
OPENID_CLIENT_ID=<removed>
HOST_HOSTNAME=<removed>
TCP_PORT_8080=8088
HOST_CONTAINERNAME=Guacamole
OPENID_ISSUER=<removed>
EXTENSION_PRIORITY=postgresql, openid
DATABASE_USERNAME=guacamole
OPENID_JWKS_ENDPOINT=<removed>
TZ=Europe/Berlin
HOST_OS=Unraid
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
LC_ALL=C.UTF-8
LD_LIBRARY_PATH=/opt/guacamole/lib
HOME=/config
GUACAMOLE_HOME=/config/guacamole
GUACD_LOG_LEVEL=info
PUID=99
PGID=100

/mnt/cache/appdata/guacamole/config -> /config
/mnt/cache/appdata/guacamole/recordings -> /var/lib/guacamole/recordings

/mnt/user/appdata/guacamole#
.
├── config
│   ├── guacamole
│   │   ├── extensions
│   │   │   ├── 1-guacamole-auth-sso-openid.jar
│   │   │   ├── guacamole-auth-jdbc-postgresql.jar
│   │   │   └── guacamole-history-recording-storage.jar
│   │   ├── guacamole.properties
│   │   ├── lib
│   │   │   └── postgresql-42.7.10.jar
│   │   └── user-mapping.xml
│   └── log
│       ├── supervisord.log
│       ├── tomcat
│       │   ├── catalina.2026-03-08.log
│       │   ├── catalina.2026-03-11.log
│       │   ├── catalina.2026-03-13.log
│       │   ├── catalina.out
│       │   ├── host-manager.2026-03-08.log
│       │   ├── host-manager.2026-03-11.log
│       │   ├── host-manager.2026-03-13.log
│       │   ├── localhost.2026-03-08.log
│       │   ├── localhost.2026-03-11.log
│       │   ├── localhost.2026-03-13.log
│       │   ├── localhost_access_log.2026-03-08.txt
│       │   ├── localhost_access_log.2026-03-09.txt
│       │   ├── localhost_access_log.2026-03-10.txt
│       │   ├── localhost_access_log.2026-03-11.txt
│       │   ├── localhost_access_log.2026-03-12.txt
│       │   ├── localhost_access_log.2026-03-13.txt
│       │   ├── manager.2026-03-08.log
│       │   ├── manager.2026-03-11.log
│       │   └── manager.2026-03-13.log
│       └── tomcat.log
└── recordings

I think the download trigger for postgre*.jar is not started correctly.

I did quickly check your code at: https://github.com/cleao01/UnraidDockerGuacamole/blob/main/image/etc/firstrun/firstrun.sh#L261. The else case on line 261 is no else case. It should run in my opinion if extension priority postgresql is set and if no postgresql*.jar file is in /config/guacamole/lib. Do you think so also?

Is the one you copy manualy?:

In line 261 i test if no postgresql extension exists , its the same of testing the connector because the two must be present

Edited March 13Mar 13 by Cabé

Yeah exactly. That‘s the one I copied manually.

Hello all. I am hoping that someone could be kind enough to assist me with a little issue that I am having. I spun up the ApacheGuacamole container from the CA store. I plan on using it alongside Authentik. When visiting my Guacamole URL (guac.mydomain.com) I am presented with the Authentik login screen. after successfully logging in I am taken to the Guacamole interface where I see Recent and All Connections (both are empty)

If I head over to settings the only two options that I am presented with are Active Sessions and Preferences. If I set the OPT_OPENID value to "N" in the ApacheGuacamole unraid app settings I can bypass Authentik. I then create the exact same users that I have setup in Authentik. It appears that I have absolutely no admin privileges. I can provide screenshots once I know what is required of me. Your time and assistance will be greatly appreciated. Peter

Edited May 24May 24 by peterbatah

Hello Peter, pheraps you are using the template from jasonbean, add the application from unraid store and give it other name, i think it will pull the correct template

Edited May 24May 24 by Cabé