Introduction

Apache Guacamole is a clientless remote desktop gateway that supports protocols such as RDP, VNC, and SSH. The major advantage of Guacamole is that it does not require client software. You only need a web browser to access your servers and desktops.

In this article, we will guide you through the installation of Apache Guacamole on a GreenCloud VPS using Docker Compose, with PostgreSQL as the backend database. By the end of this tutorial, you will have a fully functional remote desktop gateway that you can access securely through a browser.

We will cover the following steps:

1. Update the system and install Docker

2. Set up Docker Compose for Guacamole

3. Initialize the PostgreSQL database

4. Start the Guacamole services

5. Access and log in to Guacamole

1. Update the System and Install Docker

Update system packages

Keeping your system updated ensures you have the latest security patches and bug fixes.

dnf update

Add the Docker repository

Docker is not included in the default CentOS/Stream repositories. Add the official Docker repository:

dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

Install Docker and required plugins

Install Docker CE and its associated tools:

dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Explanation of packages:

• docker-ce: Docker Community Edition engine

• docker-ce-cli: Command-line interface for Docker

• containerd.io: Container runtime

• docker-buildx-plugin: Supports advanced image building

• docker-compose-plugin: Modern plugin for docker compose

Enable and start Docker

Enable Docker to run at system boot and start it immediately:

systemctl enable --now docker

Verify the installation

Check the Docker and Docker Compose versions:

docker --version
docker compose version

If you see version outputs, Docker is installed successfully.

2. Set Up Apache Guacamole with Docker Compose

Create a working directory

All configuration files will be stored in the/opt/guacamole directory.

mkdir -p /opt/guacamole
cd /opt/guacamole

Create the docker-compose.yml file

This file defines three services: PostgreSQL, guacd, and Guacamole.

cat > docker-compose.yml <<'YML'
services:
guacamole-db:
image: postgres:15
container_name: guac-db
environment:
POSTGRES_USER: guacuser
POSTGRES_PASSWORD: StrongPassword123!
POSTGRES_DB: guacamole_db
volumes:
- db_data:/var/lib/postgresql/data
restart: unless-stoppedguacd:
image: guacamole/guacd:1.5.5
container_name: guacd
restart: unless-stopped

guacamole:
image: guacamole/guacamole:1.5.5
container_name: guacamole
environment:
POSTGRES_HOSTNAME: guacamole-db
POSTGRES_DATABASE: guacamole_db
POSTGRES_USER: guacuser
POSTGRES_PASSWORD: StrongPassword123!
GUACD_HOSTNAME: guacd
GUACD_PORT: 4822
ports:
- "8080:8080"
depends_on:
- guacamole-db
- guacd
restart: unless-stopped

volumes:
db_data:
YML

Details:

• guacamole-db: PostgreSQL container storing users and configuration

• guacd: Proxy daemon that manages remote desktop protocols

• guacamole: Web application connecting to PostgreSQL and guacd

• Volumes: Persistent storage for PostgreSQL data

• Port 8080: Exposes the Guacamole web UI

3. Initialize the PostgreSQL Database

Start the database container

Run only the PostgreSQL container to initialize the database:

docker compose up -d guacamole-db

Wait for the database

Allow PostgreSQL to fully start before initializing:

sleep 10

Generate the schema

Guacamole provides a script to generate the SQL schema:

docker run --rm guacamole/guacamole:1.5.5 /opt/guacamole/bin/initdb.sh --postgresql > initdb.sql

This creates initdb.sql with all necessary tables, indexes, and default data.

Import the schema

Load the schema into the running PostgreSQL container:

docker exec -i guac-db psql -U guacuser -d guacamole_db < initdb.sql

Verify the database

Check that tables were created successfully:

docker exec -it guac-db psql -U guacuser -d guacamole_db -c "\dt"

You should see a list of Guacamole tables.

4. Start Guacamole

Launch all services

Now bring up the complete Guacamole stack:

docker compose up -d

Check container status

Confirm that all services are running:

docker compose ps

View Guacamole logs

Inspect the logs to verify a successful startup:

docker logs guacamole --tail=100

Access the web interface

Open a browser and go to:

http://your-server-ip:8080/guacamole

Default login credentials

• Username: guacadmin

• Password: guacadmin

Change the default password immediately after logging in.

Conclusion

You have now deployed Apache Guacamole on a GreenCloud VPS using Docker Compose. This setup allows you to manage remote desktops and servers directly through a web browser, without installing additional software.

Next steps to improve your deployment:

• Change the default admin password

• Configure HTTPS with a reverse proxy (such as Nginx and Let’s Encrypt)

• Regularly update Docker images for security and stability

With this foundation, you can now build a secure and centralized remote access solution for managing both Windows and Linux servers.