How to Install Apache Guacamole with Docker on Ubuntu 22.04: A Complete Guide

How to Install Apache Guacamole with Docker on Ubuntu 22.04: A Complete Guide

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

  1. Prerequisites
  2. 1. Install Docker and Docker Compose
  3. 2. Set Up the Guacamole Environment
  4. 3. Create the Docker Compose File
  5. 4. Configure Guacamole
  6. 5. Start the Docker Containers
  7. 6. Initialize the Guacamole Database
  8. 7. Create an Admin User
  9. 8. Access the Guacamole Web Interface
  10. 9. Add Remote Connections
  11. 10. Secure Guacamole
  12. 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 the admin 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.

  1. Click on the Settings icon in the top right corner.
  2. Select Connections.
  3. Click on New Connection.
  4. 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.
  5. 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:

  1. Install Docker and Docker Compose: Set up Docker to manage containers.
  2. Create Docker Compose File: Define services for MySQL, guacd, and Guacamole.
  3. Configure Guacamole: Set up properties and extensions.
  4. Start Containers: Launch the services using Docker Compose.
  5. Initialize Database: Apply the necessary SQL schemas to MySQL.
  6. Create Admin User: Secure your Guacamole installation by adding an admin account.
  7. Access Web Interface: Log in and configure remote connections.
  8. 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!

 

Comments

No comments yet. Why don’t you start the discussion?

Leave a Reply

Your email address will not be published. Required fields are marked *