Skip to main content

Remote Access Gateway Service via Guacamole

Field

Details

Document Type

Deployment Guide: Remote Access Gateway

Applies To

Docker, Apache Guacamole, MySQL, Traefik Proxy

Audience

2nd Line / Systems Administrator / DevOps

Author

AK. Udofeh

Last Updated

March 2026
Overview

This document provides guidance for deploying Apache Guacamole behind Traefik with a MySQL backend using built-in authentication. The solution enables secure, browser-based remote access to systems over RDP, SSH, and VNC without requiring any client-side software, exposing internal services directly, or relying on traditional VPN access.

By centralising remote connectivity through a reverse proxy, the platform acts as a controlled access gateway where users authenticate once and securely connect to target machines from anywhere. This approach improves security, simplifies access management, and provides a unified interface for managing remote sessions across Windows and Linux environments.

The document also covers common issues encountered during initial deployment, particularly database initialisation and connectivity problems, along with validated fixes and operational guidance for reliable redeployment.

Deployment Architecture

User  > Traefik > Guacamole > guacd > Target System (RDP / SSH / VNC)

                                 ↓

       MySQL (users, sessions, config)

Before You Start

Check

Where

Docker host accessible

Host system

DB volume identified

Portainer → Volumes

Domain resolves correctly

DNS / Browser
Deployment — High Level Steps
  1.  Prepare project structure and environment variables
  2.  Generate Guacamole database schema
  3.  Configure Docker Compose
  4.  Deploy services
  5.  Initialise database (first run only)
  6.  Access Guacamole web interface

Refer to repository for full configuration: https://github.com/ak-wizzy/guacamole-rdg 

Database Initialisation (Critical Step)

This is the only mandatory post-deployment step

After deploying the stack for the first time:

  1.  Generate the Guacamole schema (from host)
  2.  Apply the schema to the MySQL container
  3.  Confirm tables exist in the database

Verification command inside MySQL:

SHOW TABLES;

Expected: Multiple tables (e.g. guacamole_user, guacamole_connection)

Accessing the Platform

Navigate to: https://your-domain/guacamole

Default credentials:

Username: guacadmin

Password: guacadmin

Change credentials immediately after first login

Setting up an RDP connection (Windows)

Step 1:  Prepare the Windows machine

On the target machine:

1. Enable Remote Desktop

Settings >  System  > Remote Desktop >  Enable

2. Allow through firewall

Windows Defender Firewall > Allow Remote Desktop

3. Get IP address

ipconfig

Step 2:  Create connection in Guacamole

1. Login to Guacamole

2. Go to:

Settings >  Connections >  New Connection

Step 3:  Configure RDP

Fill in:

Basic:

  •  Name: My Windows Server
  •  Protocol: RDP

Parameters:

  • Hostname: 192.168.x.x (or DNS)
  • Port: 3389

Authentication:

  • Username: Windows username
  • Password: Windows password
  • Domain: (optional, for AD)

Step 4:  Save and connect

Click connection >  you should land in Windows desktop via browser

Pro tips (RDP)

  • Use internal IP if same network/VPN
  • For cloud/VPS → ensure port 3389 open
  • Enable NLA (Network Level Auth) for security
  • Add:

“Ignore certificate” if self-signed

Setting up an SSH connection (Linux)

Step 1:  Prepare Linux machine

On target machine:

sudo apt update

sudo apt install openssh-server -y

Start SSH:

sudo systemctl enable ssh

sudo systemctl start ssh

Check IP:

ip a

Step 2:  Create connection in Guacamole

Same path:

Settings > Connections  > New Connection

Step 3:  Configure SSH

Basic:

  • Name: My Linux Server
  • Protocol: SSH

Parameters:

  • Hostname: 192.168.x.x
  • Port: 22

Authentication:

  • Username: ubuntu (or your user)
  • Password: OR use private key

Step 4:  Save and connect

You’ll get a terminal in your browser

 Pro tips (SSH)

  • Use SSH keys instead of password (more secure)
  • Paste private key into Guacamole field
  • Disable password auth on server (optional hardening)
Common issues (quick fixes)

Connection fails

  • Check target machine is reachable:

    ping <IP>

RDP black screen

  • Disable:

o bitmap caching

o or enable “force lossless”

SSH timeout

  • Check:

    sudo systemctl status ssh

“Connection refused”

  • Port closed OR service not running
Final mental model
  • Guacamole = browser gateway
  • guacd     = protocol translator
  • Target    = actual machine
Back to top