Guacamole

Apache Guacamole provides web-based remote desktop access to your devenv-full container, accessible from any modern web browser.

Architecture

Components

Initial Setup

One-Time Database Initialization

After starting services, run the initialization script:

cd docker/guacamole
chmod +x init.sh
./init.sh

This script:

1. Downloads the Guacamole database schema
2. Applies the schema to PostgreSQL
3. Creates a default RDP connection to devenv-full

Default Connection Created

After initialization, a connection named "devenv-full RDP" is pre-configured:

Accessing Guacamole

Local Development

http://localhost:8081/guacamole

Coolify Deployment (Production)

https://lab1-helsinki.guacamole.mks2508.systems

First Login

1. Open Guacamole in your browser
2. Login with guacadmin / guacadmin
3. IMPORTANT: Change your password immediately
4. Click on "devenv-full RDP" to connect to the desktop

Adding New Connections

Via Web UI

1. Login to Guacamole
2. Go to Settings → Connections
3. Click New Connection
4. Configure:
   • Name: Descriptive name
   • Protocol: RDP, VNC, or SSH
   • Parameters: hostname, port, credentials

Example: Add SSH Connection

1. Create new connection
2. Set protocol to SSH
3. Configure:
   • Hostname: devenv
   • Port: 22
   • Username: root
   • Password: (use key-based auth instead)

Configuration

Environment Variables

Configure in docker/.env:

# Database
GUACAMOLE_DB_NAME=guacamole_db
GUACAMOLE_DB_USER=guacamole_user
GUACAMOLE_DB_PASSWORD=guacamole_pass

Port Mapping

Changed from default 8080 to 8081 to avoid conflict with Coolify:

ports:
  - "8081:8080"  # Host:Container

Troubleshooting

Connection Failed

Symptom: "Connection failed" error in Guacamole

Solutions:

1. Check devenv-full is healthy:

   docker compose ps devenv

2. Check network connectivity:

   docker exec mks-guacamole ping devenv

3. Check xrdp is running:

   docker exec mks-devenv-full supervisorctl status xrdp

Database Errors

Symptom: Database-related errors in logs

Solutions:

1. Check PostgreSQL is healthy:

   docker compose ps guacamole-postgres

2. Re-run initialization:

   cd guacamole && ./init.sh

3. Reset database (last resort):

   docker compose down
   docker volume rm mks-guacamole-db
   docker compose up -d guacamole-postgres guacamole-guacd guacamole
   cd guacamole && ./init.sh

Blank Screen After Connection

Symptom: Connection succeeds but shows blank screen

Solutions:

1. Check Xvfb is running:

   docker exec mks-devenv-full supervisorctl status xvfb

2. Check Xfce4 is running:

   docker exec mks-devenv-full supervisorctl status xfce4

3. Check display resolution - lower it if needed in .env:

   VNC_RESOLUTION=1280x720

Reset Everything

# Stop all services
docker compose down

# Remove database volume
docker volume rm mks-guacamole-db

# Start fresh
docker compose up -d

# Re-initialize
cd guacamole && ./init.sh