Apache Guacamole is a clientless remote desktop gateway that supports protocols like VNC, RDP, and SSH. Using Docker simplifies the installation and management process, avoiding dependency issues. This comprehensive guide will walk you through installing Apache Guacamole using Docker on Ubuntu 22.04.
Table of Contents
- Prerequisites
- 1. Install Docker and Docker Compose
- 2. Set Up the Guacamole Environment
- 3. Create the Docker Compose File
- 4. Configure Guacamole
- 5. Start the Docker Containers
- 6. Initialize the Guacamole Database
- 7. Create an Admin User
- 8. Access the Guacamole Web Interface
- 9. Add Remote Connections
- 10. Secure Guacamole
- 11. Conclusion
Prerequisites
Before you begin, ensure you have the following:
- An Ubuntu 22.04 server with root or sudo privileges.
- Internet connectivity to download necessary packages and Docker images.
1. Install Docker and Docker Compose
a. Update the System
sudo apt update
sudo apt upgrade -y
b. Install Required Packages
sudo apt install -y ca-certificates curl gnupg lsb-release
c. Add Docker’s Official GPG Key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
d. Set Up the Docker Repository
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
e. Install Docker Engine
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
f. Verify Docker Installation
sudo docker run hello-world
If Docker is installed correctly, you should see a “Hello from Docker!” message.
2. Set Up the Guacamole Environment
a. Create a Directory for Guacamole
mkdir -p ~/guacamole
cd ~/guacamole
3. Create the Docker Compose File
a. Create a docker-compose.yml
File
nano docker-compose.yml
Add the following content to the docker-compose.yml
file:
version: '3.8'
services:
db:
image: mysql:8.0
container_name: guac_db
restart: always
environment:
MYSQL_DATABASE: guacamole_db
MYSQL_USER: guacamole_user
MYSQL_PASSWORD: strong_password
MYSQL_ROOT_PASSWORD: root_password
volumes:
- db_data:/var/lib/mysql
networks:
- guacamole_network
guacd:
image: guacamole/guacd:latest
container_name: guacd
restart: always
ports:
- "4822:4822"
networks:
- guacamole_network
guacamole:
image: guacamole/guacamole:latest
container_name: guacamole
restart: always
ports:
- "8080:8080"
environment:
GUACD_HOSTNAME: guacd
MYSQL_HOSTNAME: db
MYSQL_PORT: 3306
MYSQL_DATABASE: guacamole_db
MYSQL_USER: guacamole_user
MYSQL_PASSWORD: strong_password
depends_on:
- guacd
- db
networks:
- guacamole_network
volumes:
- ./extensions:/etc/guacamole/extensions
- ./guacamole.properties:/etc/guacamole/guacamole.properties
volumes:
db_data:
networks:
guacamole_network:
driver: bridge
Note:
strong_password
: Replace with a strong password for the Guacamole MySQL user.root_password
: Replace with a strong password for the MySQL root user.
4. Configure Guacamole
a. Create the Extensions Directory
mkdir -p extensions
b. Download the Guacamole JDBC Authentication Extension
wget https://downloads.apache.org/guacamole/1.5.4/binary/guacamole-auth-jdbc-1.5.4.tar.gz
tar -xzf guacamole-auth-jdbc-1.5.4.tar.gz
cp guacamole-auth-jdbc-1.5.4/mysql/guacamole-auth-jdbc-mysql-1.5.4.jar extensions/
Ensure you download the version compatible with your Guacamole installation. Check for the latest version at Apache Guacamole Downloads.
c. Create the guacamole.properties
File
nano guacamole.properties
Add the following content:
guacd-hostname: guacd
guacd-port: 4822
auth-provider: net.sourceforge.guacamole.net.auth.mysql.MySQLAuthenticationProvider
mysql-hostname: db
mysql-port: 3306
mysql-database: guacamole_db
mysql-username: guacamole_user
mysql-password: strong_password
Replace strong_password
with the password you set for guacamole_user
in the docker-compose.yml
file.
5. Start the Docker Containers
In the ~/guacamole
directory, run the following command to start the services:
sudo docker compose up -d
This will start the MySQL database, guacd daemon, and the Guacamole web application.
6. Initialize the Guacamole Database
a. Copy Schema Files to the MySQL Container
sudo docker cp guacamole-auth-jdbc-1.5.4/mysql/schema/ guac_db:/schema/
b. Execute Schema Scripts
sudo docker exec -it guac_db bash
mysql -u root -p
Enter the MySQL root password you set in the docker-compose.yml
file.
Within the MySQL prompt, execute the following commands:
USE guacamole_db;
SOURCE /schema/001-create-schema.sql;
SOURCE /schema/002-create-admin-user.sql;
EXIT;
These scripts will set up the necessary database schema and create an initial admin user.
c. Exit the MySQL Container
exit
d. Restart the Guacamole Container
sudo docker restart guacamole
7. Create an Admin User
By default, an admin user is created by the schema scripts. However, to ensure security, it’s recommended to create your own admin user with a hashed password.
a. Access the MySQL Container
sudo docker exec -it guac_db bash
mysql -u root -p
b. Create the Admin User
USE guacamole_db;
INSERT INTO guacamole_user (username, password_hash, password_salt, password_hash_algorithm)
VALUES (
'admin',
UNHEX(SHA2('your_password', 256)),
NULL,
'SHA-256'
);
GRANT SELECT, INSERT, UPDATE, DELETE ON guacamole_db.* TO 'guacamole_user'@'%';
FLUSH PRIVILEGES;
EXIT;
Note:
- Replace
'your_password'
with a strong password for theadmin
user. - Using SHA-256 ensures that passwords are securely hashed.
8. Access the Guacamole Web Interface
Open your web browser and navigate to:
http://your_server_ip:8080/guacamole/
Replace your_server_ip
with the actual IP address of your Ubuntu server.
Default Login Credentials
- Username: admin
- Password: your_password
Use the credentials you set in the previous step.
9. Add Remote Connections
After logging in, you can add remote connections (RDP, VNC, SSH) through the Guacamole interface.
- Click on the Settings icon in the top right corner.
- Select Connections.
- Click on New Connection.
- Fill in the connection details:
- Name: A descriptive name for the connection.
- Protocol: Choose RDP, VNC, or SSH.
- Parameters: Enter the necessary details like IP address, port, and login credentials.
- Click Save to add the connection.
You can now use the added connections to access your remote desktops.
10. Secure Guacamole
a. Set Up HTTPS with Nginx
To secure your Guacamole web interface, it’s recommended to set up HTTPS using Nginx as a reverse proxy.
i. Install Nginx
sudo apt install nginx -y
ii. Configure Nginx
sudo nano /etc/nginx/sites-available/guacamole
Add the following configuration:
server {
listen 80;
server_name your_domain_or_IP;
location /guacamole/ {
proxy_pass http://localhost:8080/guacamole/;
proxy_buffering off;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
}
Replace your_domain_or_IP
with your server’s domain name or IP address.
iii. Enable the Nginx Configuration
sudo ln -s /etc/nginx/sites-available/guacamole /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx
iv. Obtain SSL Certificates with Let’s Encrypt (Optional)
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d your_domain
Follow the prompts to obtain and install SSL certificates.
b. Configure Firewall
If you are using UFW (Uncomplicated Firewall), allow the necessary ports:
sudo ufw allow 22/tcp # SSH
sudo ufw allow 80/tcp # HTTP
sudo ufw allow 443/tcp # HTTPS
sudo ufw allow 4822/tcp # guacd
sudo ufw enable
Note: If you set up Nginx as a reverse proxy with HTTPS, you might not need to expose port 8080
externally.
c. Regular Updates and Maintenance
- Update Docker and Containers: Periodically pull the latest images and restart containers.
sudo docker compose pull sudo docker compose up -d
- Monitor Logs: Check the logs of your containers to ensure everything is running smoothly.
sudo docker logs guacamole sudo docker logs guacd sudo docker logs guac_db
11. Conclusion
You have successfully installed and configured Apache Guacamole using Docker on Ubuntu 22.04. This setup allows you to manage and access remote desktops through a web interface securely and efficiently.
Here is a quick recap of the steps:
- Install Docker and Docker Compose: Set up Docker to manage containers.
- Create Docker Compose File: Define services for MySQL, guacd, and Guacamole.
- Configure Guacamole: Set up properties and extensions.
- Start Containers: Launch the services using Docker Compose.
- Initialize Database: Apply the necessary SQL schemas to MySQL.
- Create Admin User: Secure your Guacamole installation by adding an admin account.
- Access Web Interface: Log in and configure remote connections.
- Secure Guacamole: Implement HTTPS and configure your firewall.
If you encounter any issues, refer to the Docker and Apache Guacamole documentation for further assistance:
Happy remote managing!