# Apache Guacamole Remote Desktop

> Clientless remote desktop gateway supporting VNC, RDP, and SSH.

- Category: Security & Networking
- Difficulty: intermediate
- Components: guacamole, guacd, postgresql, nginx
- Tags: remote-desktop, vnc, rdp, ssh, guacamole
- Source: https://docker.recipes/security/apache-guacamole

## Overview

Apache Guacamole is a clientless remote desktop gateway that enables access to desktop environments through a web browser. Originally developed by the Apache Software Foundation, Guacamole eliminates the need for client-side software by implementing remote desktop protocols (VNC, RDP, SSH) through HTML5 and JavaScript, making it accessible from any device with a modern web browser. This deployment creates a complete four-tier architecture with guacd (the native proxy daemon), the Guacamole web application, PostgreSQL for user authentication and connection management, and NGINX as a reverse proxy for enhanced security and performance. The stack provides enterprise-grade remote access capabilities with features like session recording, file transfer, two-factor authentication via TOTP, and comprehensive user management through a web-based administration interface. This configuration is ideal for organizations implementing zero-trust remote access, managed service providers offering hosted desktop solutions, educational institutions providing lab access, and IT teams requiring secure administrative access to infrastructure without exposing RDP or SSH directly to the internet.

## Features

- Protocol-agnostic remote access supporting VNC, RDP, SSH, and Telnet connections through a single web interface
- Built-in TOTP two-factor authentication for enhanced security and compliance requirements
- Session recording capabilities with dedicated storage volumes for audit trails and compliance
- File transfer support between client browsers and remote systems through the guacd proxy daemon
- PostgreSQL-backed user management with role-based access control and connection sharing
- Multi-protocol connection gateway allowing different remote desktop technologies from one portal
- NGINX reverse proxy providing SSL termination, load balancing, and protection against direct application exposure
- Persistent connection state management enabling session resumption and connection pooling

## Use cases

- Remote work infrastructure providing secure browser-based access to corporate desktops and servers
- Managed service provider offerings for hosted virtual desktop infrastructure (VDI) solutions
- Educational computer labs accessible remotely without requiring software installation on student devices
- IT administration portal for secure server management without exposing SSH or RDP ports publicly
- Development environment access for distributed teams working on shared development servers
- Customer support systems allowing technicians to access client systems through controlled gateway
- Compliance-focused environments requiring session recording and centralized access logging

## Prerequisites

- Minimum 2GB RAM recommended for full stack operation with PostgreSQL and concurrent user sessions
- Docker host with port 8080 available for NGINX reverse proxy access
- Generated PostgreSQL initialization script (initdb.sql) containing Guacamole database schema
- Understanding of remote desktop protocols (VNC, RDP, SSH) and target system configuration
- Network access from Docker host to target remote desktop systems
- SSL certificates for production deployment with sensitive remote access

## docker-compose.yml

```yaml
services:
  guacamole:
    image: guacamole/guacamole:latest
    container_name: guacamole
    environment:
      - GUACD_HOSTNAME=guacd
      - POSTGRESQL_HOSTNAME=db
      - POSTGRESQL_DATABASE=guacamole_db
      - POSTGRESQL_USER=guacamole
      - POSTGRESQL_PASSWORD=${DB_PASSWORD}
      - TOTP_ENABLED=true
    depends_on:
      - guacd
      - db
    networks:
      - guacamole-network
    restart: unless-stopped

  guacd:
    image: guacamole/guacd:latest
    container_name: guacd
    volumes:
      - guacd-drive:/drive:rw
      - guacd-record:/record:rw
    networks:
      - guacamole-network
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: guacamole-db
    environment:
      - POSTGRES_USER=guacamole
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=guacamole_db
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./initdb.sql:/docker-entrypoint-initdb.d/initdb.sql
    networks:
      - guacamole-network
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    container_name: guacamole-nginx
    ports:
      - "8080:80"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      - guacamole
    networks:
      - guacamole-network
    restart: unless-stopped

volumes:
  guacd-drive:
  guacd-record:
  postgres-data:

networks:
  guacamole-network:
    driver: bridge
```

## .env

```bash
# Apache Guacamole
DB_PASSWORD=secure_guacamole_password

# Generate initdb.sql with:
# docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgresql > initdb.sql
```

## Usage notes

- Web UI at http://localhost:8080/guacamole
- Default login: guacadmin/guacadmin
- Generate initdb.sql before first run
- Supports VNC, RDP, SSH, Telnet
- Enable TOTP for 2FA security

## Troubleshooting

- guacamole container fails to start: Verify DB_PASSWORD environment variable is set and PostgreSQL service is healthy
- Cannot connect to remote desktop: Check that guacd container has network access to target systems and protocols are properly configured
- Database connection errors: Ensure initdb.sql schema is loaded and PostgreSQL container has sufficient memory allocated
- Session recordings not saving: Verify guacd-record volume is properly mounted and container has write permissions
- NGINX 502 Bad Gateway: Check that guacamole service is running and accessible on guacamole-network
- TOTP authentication not working: Verify system clocks are synchronized between Guacamole server and authentication devices

