Deployment Overview of Apache Guacamole + Xfce on Server¶

Prerequisites and Basic Requirements¶

To ensure a successful deployment, the server must meet the following requirements:

Operating System: Ubuntu (Focal/Lunar), Debian, or RHEL-based distributions (CentOS, Rocky Linux, AlmaLinux).
Privileges: Root or sudo access is required for package installation and service management.
Network Ports:
443 (HTTPS) for external web access via Nginx.
8080 (HTTP) for the internal Tomcat application service.
3389 (RDP) for remote desktop connections.

FQDN of the final panel on the hostkey.in domain¶

The application is accessible via a specific subdomain based on the server ID. The template for the URL is as follows:

Parameter	Value
Prefix	`guacamole`
Domain	`hostkey.in`
Full template	`guacamole{Server_ID}.hostkey.in/guacamole/`

File and Directory Structure¶

The following directories are used for configuration, application data, and certificates:

/etc/guacamole/: Main configuration directory for Guacamole (contains user-mapping.xml, guacd.conf, etc.).
/etc/guacamole/extensions/: Directory for Guacamole extensions.
/etc/guacamole/lib/: Directory for Guacamole libraries.
/var/lib/tomcat9/webapps/: Location of the Guacamole web application file (guacamole.war).
/root/nginx/: Contains the Docker Compose configuration for the Nginx reverse proxy and SSL management.

Application installation process¶

The installation process varies slightly depending on the operating system but follows a consistent logic:

Dependency Installation: The system installs essential libraries including gawk, curl, libssl-dev, freerdp2-dev, libavcodec-dev, and several others required for video/audio processing and RDP support.
Guacamole Server Compilation:
The latest source code (guacamole-server-*.tar.gz) is downloaded from the Apache official repository.
The source is extracted in /root.
The software is compiled using ./configure, make, and make install with the initialization directory set to /etc/init.d.
Web Application Deployment:
Tomcat9 is installed via the system package manager.
The Guacamole binary (guacamole.war) is downloaded and placed in the Tomcat webapps directory.
Desktop Environment (Ubuntu only):
xubuntu-desktop and xrdp are installed to provide a graphical interface.
A custom user named user is created with specific group permissions for XRDP.

Access Rights and Security¶

Firewall: Ensure port 443 is open for HTTPS traffic.
User Management:
A system user user is created to handle the Xfce desktop session via XRDP.
Guacamole access is managed through a user-mapping.xml file, which defines authorized users and their connection parameters.
XRDP Security: The configuration modifies /etc/xrdp/xrdp.ini to adjust encryption levels and color depth for better performance.

Databases¶

The application uses an XML-based user mapping (user-mapping.xml) for authentication by default, which stores credentials in a hashed format (MD5).

Docker Containers and Their Deployment¶

The deployment utilizes a single containerized service to manage the Nginx reverse proxy and SSL certificates:

Nginx Certbot Container

Image: jonasal/nginx-certbot:latest
Ports: Uses host network mode.
Volumes:
nginx_secrets:/etc/letsencrypt (SSL Certificates)
/data/nginx/user_conf.d:/etc/nginx/user_conf.d (Nginx configuration)
Environment Variables: [email protected]
Restart Policy: unless-stopped

Custom Scripts and Additional Setup¶

The following actions are performed during the setup to ensure proper environment configuration:

Xfce Session Initialization: A script is placed at /usr/local/bin/start-xubuntu to correctly initialize the XDG environment variables, ensuring the desktop session loads properly via XRDP.
Environment Configuration: The GUACAMOLE_HOME=/etc/guacamole variable is appended to /etc/default/tomcat9 to ensure Tomcat can locate the Guacamole configuration files.
Service Initialization: The ldconfig command is executed after compiling the server components to update shared library links for guacd.

Application Update Instructions¶

To update the main application:

Guacamole Server: Re-download the latest source tarball, re-run ./configure, make, and make install.
Web Application: Replace the existing /var/lib/tomcat9/webapps/guacamole.war with the new version from the Apache repository.
Service Restart: After any manual changes or updates, restart the services:
```
systemctl restart tomcat9
systemctl restart guacd
```

Location of configuration files and data¶

Guacamole Configs: /etc/guacamole/
Nginx Proxy Configs: /data/nginx/user_conf.d/
SSL Certificates: Managed within the Docker volume nginx_secrets.

Available ports for connection¶

Service	Port	Protocol
Web Interface (HTTPS)	443	TCP
Tomcat Internal	8080	TCP
RDP (via Guacamole)	3389	TCP

Starting and Stopping the application¶

The following commands are used to manage the core services:

Start/Restart Guacamole Daemon: systemctl restart guacd
Start/Restart Web Server: systemctl restart tomtomcat9
Manage Nginx Proxy (Docker):
Navigate to /root/nginx.
Use docker compose up -d to start.
Use docker compose down to stop.

Proxy Servers¶

The application uses an Nginx container acting as a reverse proxy. It handles SSL termination via Certbot, providing secure HTTPS access to the Guacamole interface through the configured domain.