How To Install Apache Guacamole on Ubuntu 24.04 LTS

In this tutorial, we will show you how to install Apache Guacamole on Ubuntu 24.04 LTS. Apache Guacamole is a powerful, open-source remote desktop gateway that enables seamless access to your computers from anywhere, using only a web browser. It supports standard protocols like VNC, RDP, and SSH, making it an ideal solution for remote access and administration.

This article assumes you have at least basic knowledge of Linux, know how to use the shell, and most importantly, you host your site on your own VPS. The installation is quite simple and assumes you are running in the root account, if not you may need to add ‘sudo‘ to the commands to get root privileges. I will show you the step-by-step installation of the Apache Guacamole open-source remote desktop gateway on Ubuntu 24.04 (Noble Numbat). You can follow the same instructions for Ubuntu 22.04 and any other Debian-based distribution like Linux Mint, Elementary OS, Pop!_OS, and more as well.

Prerequisites

• A server running one of the following operating systems: Ubuntu and any other Debian-based distribution like Linux Mint.
• It’s recommended that you use a fresh OS install to prevent any potential issues.
• SSH access to the server (or just open Terminal if you’re on a desktop).
• At least 2 GB of RAM for optimal performance.
• Sufficient disk space for the Guacamole server and its dependencies (a minimum of 5 GB is recommended).
• An active internet connection. You’ll need an internet connection to download the necessary packages and dependencies.
• An Ubuntu 24.04 system with root access or a user with sudo privileges.

Install Apache Guacamole on Ubuntu 24.04

Step 1. Update System Packages.

 Before proceeding with the installation, ensure your system packages are up to date:

sudo apt update
sudo apt upgrade

This command will refresh the package lists and upgrade any outdated packages to their latest versions. Keeping your system up-to-date is a good practice for maintaining stability and security.

Step 2. Installing Dependencies.

Install the required build tools and dependencies:

sudo apt install gcc g++ make libcairo2-dev libjpeg-turbo8-dev libpng-dev libtool-bin libossp-uuid-dev libavcodec-dev libavutil-dev libswscale-dev freerdp2-dev libpango1.0-dev libssh2-1-dev libvncserver-dev libtelnet-dev libssl-dev libvorbis-dev libwebp-dev

Step 3.  Installing Guacamole Server.

The Guacamole server, guard, is the core component that proxies the remote desktop connections. To install it, follow these steps:

Download the latest Guacamole server source code from the official website. At the time of writing, the latest version is 1.5.5:

wget https://downloads.apache.org/guacamole/1.5.5/source/guacamole-server-1.5.5.tar.gz

Extract the downloaded archive:

tar -xzf guacamole-server-1.5.5.tar.gz

Change to the extracted directory:

cd guacamole-server-1.5.5

Configure the build environment:

./configure --with-init-dir=/etc/init.d

Compile and install the Guacamole server:

make
sudo make install
sudo ldconfig

Start and enable the guacd service:

sudo systemctl start guacd
sudo systemctl enable guacd

With the Guacamole server installed and running, you can now proceed to set up the database backend and install the Guacamole client.

Step 4. Setting Up the Database Backend.

Apache Guacamole uses a database to store user authentication and connection information. You can choose between MySQL and PostgreSQL. For this guide, we’ll use MySQL:

sudo apt install mysql-server

Secure the MySQL installation:

sudo mysql_secure_installation

Follow the prompts to set a root password and configure the security options.

Log in to the MySQL shell:

sudo mysql -u root -p

Create a new database and user for Guacamole:

CREATE DATABASE guacamole_db;
CREATE USER 'guacamole_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT SELECT, INSERT, UPDATE, DELETE ON guacamole_db.* TO 'guacamole_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Download the Guacamole MySQL extension:

wget https://downloads.apache.org/guacamole/1.5.5/binary/guacamole-auth-jdbc-1.5.5.tar.gz

Extract the downloaded archive and copy the MySQL extension to the /etc/guacamole/extensions directory:

tar -xzf guacamole-auth-jdbc-1.5.5.tar.gz
sudo mkdir -p /etc/guacamole/extensions
sudo cp guacamole-auth-jdbc-1.5.5/mysql/guacamole-auth-jdbc-mysql-1.5.5.jar /etc/guacamole/extensions/

The database backend is now set up, and you can proceed with installing and configuring Tomcat.

Step 5. Installing and Configuring Tomcat.

Apache Tomcat serves the Guacamole client web application. Follow these steps to install and configure Tomcat:

Install Tomcat and its dependencies:

sudo apt install tomcat9 tomcat9-admin tomcat9-common tomcat9-user

Start and enable the Tomcat service:

sudo systemctl start tomcat9
sudo systemctl enable tomcat9

Create a symbolic link from the Guacamole client .war file to the Tomcat webapps directory:

sudo ln -s /etc/guacamole/guacamole.war /var/lib/tomcat9/webapps/

Configure the guacamole.properties file:

sudo nano /etc/guacamole/guacamole.properties

Add the following lines to the file:

guacd-hostname: localhost
guacd-port: 4822
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: your_password

Restart the Tomcat service to apply the changes:

sudo systemctl restart tomcat9

Step 6. Installing Guacamole Client.

The Guacamole client is a web application that allows users to access remote desktops through a web browser. To install the client, follow these steps:

wget https://downloads.apache.org/guacamole/1.5.5/binary/guacamole-1.5.5.war

Create the /etc/guacamole directory and move the downloaded .war file there:

sudo mkdir /etc/guacamole
sudo mv guacamole-1.5.5.war /etc/guacamole/guacamole.war

Create a symbolic link from the Guacamole .war file to the Tomcat webapps directory:

sudo ln -s /etc/guacamole/guacamole.war /var/lib/tomcat9/webapps/

Create the guacamole.properties file:

sudo nano /etc/guacamole/guacamole.properties

Add the following lines to the file:

guacd-hostname: localhost
guacd-port: 4822
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: your_password

Create the user-mapping.xml file for basic authentication:

sudo nano /etc/guacamole/user-mapping.xml

Add the following content to the file:

<user-mapping>
<authorize username="guacadmin" password="guacadmin">
<connection name="Example">
<protocol>vnc</protocol>
<param name="hostname">localhost</param>
<param name="port">5900</param>
</connection>
</authorize>
</user-mapping>

Restart the Tomcat service to apply the changes:

sudo systemctl restart tomcat9

Step 7. Testing the Guacamole Installation.

To verify that your Apache Guacamole installation is working correctly, follow these steps:

1. 1. Open a web browser and navigate to http://your_server_ip:8080/guacamole.
   2. Log in using the default admin credentials:
      • Username: guacadmin
      • Password: guacadmin
   3. If the login is successful, you should see the Guacamole web interface with the sample VNC connection listed.
   4. Click on the connection to test it. If the connection is successful, you should see the remote desktop in your web browser

Congratulations! You have successfully installed Apache Guacamole. Thanks for using this tutorial for installing the Apache Guacamole open-source remote desktop gateway on the Ubuntu 24.04 LTS system. For additional help or useful information, we recommend you check the official Apache website.