DEV Community

Cover image for How to Install and Configure Apache Guacamole on a Linux Server
William Kwabena Akoto
William Kwabena Akoto

Posted on

How to Install and Configure Apache Guacamole on a Linux Server

#linux #sysadmin #devops #tutorial

This guide explains how to install and configure Apache Guacamole on a test server using Docker Compose. The steps are simple and suitable for both beginners and experienced administrators.

What You Will Need

Before you start, make sure you have:

  • A Linux server
  • Sudo or root privileges
  • Docker and Docker Compose

Step 1: Create the Guacamole Directory

We’ll store all files related to Guacamole in one location. Create the following directories on your server:

sudo mkdir -p /your-desired-folder/guacamole/data/mysql
Enter fullscreen mode Exit fullscreen mode

The final directory structure should look like this:

/your-desired-folder/guacamole
├── data
│   └── mysql/
├── docker-compose.yml
└── initdb.sql
Enter fullscreen mode Exit fullscreen mode
  • The data directory will store Guacamole’s configuration and data.
  • The data/mysql directory will hold the MySQL database files.
  • The initdb.sql file will be used to initialize the database.
  • The docker-compose.yml file will define how all the services work together.

Step 2: Create the Docker Compose File

Open a new file called /your-desired-folder/guacamole/docker-compose.yml and add the following content:

version: "3"
services:
  guacamole:
    image: guacamole/guacamole
    container_name: guacamole
    restart: always
    depends_on:
      - guacd
      - mysql
    ports:
      - "your-desired-port:8080"
    environment:
      GUACD_HOSTNAME: guacd
      MYSQL_HOSTNAME: mysql
      MYSQL_DATABASE: guacamole_db
      MYSQL_USER: guacuser
      MYSQL_PASSWORD: guacpass
    volumes:
      - /your-desired-folder/guacamole/data:/app/data

  guacd:
    image: guacamole/guacd
    container_name: guacd
    restart: always

  mysql:
    image: mysql:8.0
    container_name: mysql
    restart: always
    environment:
      MYSQL_ROOT_PASSWORD: rootpass
      MYSQL_DATABASE: guacamole_db
      MYSQL_USER: guacuser
      MYSQL_PASSWORD: guacpass
    volumes:
      - /your-desired-folder/guacamole/data/mysql:/var/lib/mysql
      - /your-desired-folder/guacamole:/script
Enter fullscreen mode Exit fullscreen mode

This file defines three main services:

  • guacamole – The main web application.
  • guacd – The Guacamole proxy daemon.
  • mysql – The database that stores user accounts, connection settings, and history.

Step 3: Understand the Directory Mappings

Each service in the Docker Compose file uses volumes to map directories from your host machine to the containers. This keeps your data safe even if containers are stopped or recreated.

The first mapping connects the directory /your-desired-folder/guacamole/data on the host to /app/data inside the Guacamole container. This is where Guacamole stores its configuration files and runtime data. By keeping this data on the host, it remains safe even if the container is recreated or updated.

The second mapping connects /your-desired-folder/guacamole/data/mysql on the host to /var/lib/mysql inside the MySQL container. This directory is where MySQL keeps all of its database files, such as user information, connection details, and history. Storing the database on the host ensures that all your Guacamole settings and accounts are preserved even after a restart.

The third mapping links /your-desired-folder/guacamole on the host to /script inside the MySQL container. This is mainly used to share files between the host and the database container, especially during the initial setup. For example, you can place the initdb.sql file here and use it to initialize the Guacamole database schema.

Together, these mappings make the setup reliable and persistent, ensuring you don’t lose data or configuration when updating or restarting the containers.

How It Connects Visually 

Host: /your-desired-folder/guacamole
│
├── data ---------------------> [guacamole:/app/data]
├── data/mysql ---------------> [mysql:/var/lib/mysql]
└── initdb.sql (via /script) -> [mysql:/script/initdb.sql]
Enter fullscreen mode Exit fullscreen mode

Step 4: Start the Containers & Initialize the Database

Now you can start Guacamole with Docker Compose:

cd /your-desired-folder/guacamole
docker-compose up -d
Enter fullscreen mode Exit fullscreen mode

To confirm that all containers are running, use:

docker ps
Enter fullscreen mode Exit fullscreen mode

You should see three running containers: guacamole, guacd, and mysql.

Run the following command to generate the schema file:

docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > /your-desired-folder/guacamole/initdb.sql
Enter fullscreen mode Exit fullscreen mode

Next, import the schema into the MySQL container:

docker cp /your-desired-folder/guacamole/initdb.sql mysql:/initdb.sql
docker exec -it mysql bash -c "mysql -u root -p rootpass guacamole_db < /initdb.sql"
Enter fullscreen mode Exit fullscreen mode

This creates all the necessary tables and relationships for Guacamole to work properly.

Step 5: Checking Logs and Troubleshooting

If something doesn’t work as expected, you can view the container logs:

docker logs guacamole
docker logs guacd
docker logs mysql
Enter fullscreen mode Exit fullscreen mode

Step 6: Access the Web Interface

Open your web browser and go to:

http://your-server-ip:8080/guacamole
Enter fullscreen mode Exit fullscreen mode

You will see the Guacamole login page.

Default credentials:

  • Username: guacadmin
  • Password: guacadmin

After logging in for the first time, you should change this password immediately.

Step 7: Configure Remote Connections

Once you are logged in:

  1. Click Settings in the top-right corner.
  2. Go to the Connections tab.
  3. Click New Connection to add an SSH, RDP, or VNC connection.
  4. Enter the details for the remote host you want to access.

Guacamole will connect through your browser, and you’ll be able to control remote systems directly without extra software.

Step 9: Secure the Deployment

For a test environment, running Guacamole on your desired port is fine.
However, in production, it’s recommended to:

  • Set up an Nginx reverse proxy in front of Guacamole.
  • Enable HTTPS using Let’s Encrypt or another SSL provider.
  • Limit access through your firewall (allow only necessary ports).

This ensures that your remote desktop connections remain encrypted and secure.

Conclusion

You’ve now set up and configured Apache Guacamole using Docker Compose. With this setup, you can easily access and manage remote servers through a browser without any additional client software.

By following these steps, you have a clean, organized, and reproducible deployment that can easily be moved from a test to a production environment.

Top comments (0)