Apache Guacamole - Developer Guide

Learn how to deploy Apache Guacamole on AWS with our step-by-step guide. It walks you through launching the Meetrix Guacamole AMI with CloudFormation, pointing your domain at it, logging in for the first time, and keeping the server healthy once it runs.

Apache Guacamole is an open-source, clientless remote desktop gateway. Users open a browser, log in, and get a Windows desktop over RDP, a Linux shell over SSH, or a VNC session, with nothing installed on their own device. That makes it a natural bastion host: one hardened entry point on AWS in front of machines that never need a public IP. If you would rather give each user a desktop client, our RustDesk developer guide covers a self-hosted alternative, and the OpenVPN developer guide shows how to put whole networks behind a VPN instead.

Launching the AMI

Step 1: Find and Select Guacamole AMI

1. Log in to your AWS Management Console.
2. Navigate to 'Apache Guacamole' in AWS Marketplace.

Step 2: Initial Setup & Configuration

1. Click the "Continue to Subscribe" button.
2. After subscribing, accept the terms and click "Accept Terms".
3. Wait a few minutes until processing completes, then click "Continue to Configuration".
4. Select "CloudFormation script to deploy Apache Guacamole" as the fulfillment option and choose your region. Click "Continue to Launch".
5. From the "Choose Action" dropdown, select "Launch CloudFormation" and click "Launch".

Create CloudFormation Stack

Step 1: Create a stack

1. Ensure the "Template is ready" option is selected under "Prepare template".
2. Click "Next".

Step 2: Specify stack options

1. Provide a unique "Stack name".
2. Enter the "AdminEmail" used for SSL certificate generation.
3. Enter an "AdminPassword". This is the password for the guacadmin account you log in with, so store it securely.
4. Enter a value for "DeploymentName".
5. Provide a public domain for "DomainName". Guacamole will automatically try to set up SSL if the domain is hosted on Route 53. If unsuccessful, you must set up SSL manually.
6. Choose an instance type "InstanceType" (Recommended: t3a.small).
7. Select your preferred "KeyName".
8. Enter the name of your S3 bucket for "S3Bucket", used for storing backups.
9. Set "SSHLocation" to 0.0.0.0/0, or restrict it to your own IP range.
10. Keep "SubnetCidrBlock" as 10.0.0.0/24.
11. Keep "VpcCidrBlock" as 10.0.0.0/16.
12. Click "Next".

Step 3: Configure stack options

1. Choose "Roll back all stack resources" and "Delete all newly created resources" under "Stack failure options".
2. Click "Next".

Step 4: Review

Review and verify the parameters you've entered.

1. Tick "I acknowledge that AWS CloudFormation might create IAM resources with custom names".
2. Click "Submit".

Afterward, you'll be directed to the CloudFormation stacks page. Please wait 5-10 minutes until the stack status shows CREATE_COMPLETE.

Update DNS

Step 1: Copy IP Address

Copy the public IP labeled "PublicIp" in the "Outputs" tab.

Step 2: Update DNS

1. Go to AWS Route 53 and navigate to "Hosted Zones".
2. Click Create record.
3. Add a record name matching the DomainName you entered, keep the record type as A, and paste the copied PublicIp into the value textbox.
4. Click "Create records".

Access Guacamole

Access Guacamole using the "DashboardUrl" in the Outputs tab. Until DNS and SSL are in place you can use "DashboardUrlIp" instead, which serves the dashboard over plain HTTP.

On the login screen, enter the username guacadmin and the AdminPassword you set in the stack parameters, then click "Login".

To add your first remote machine, open the user menu in the top right, go to Settings and then Connections, and click "New Connection". Choose the protocol (RDP, SSH or VNC), enter the target's hostname or private IP and its credentials, and save. The connection then appears on the Guacamole home page for every user you grant it to. The Guacamole manual lists every parameter each protocol supports.

Generate SSL Manually

Guacamole will automatically try to set up SSL when a Route 53-hosted domain is provided. If it fails, follow these steps to generate SSL manually.

Step 1: Copy IP Address

1. Follow the Update DNS steps above, if not already done.
2. Copy the Public IP indicated as "PublicIp" in the "Outputs" tab.

Step 2: Log in to the server

1. Open the terminal and go to the directory where your private key is located.
2. Run the following command, replacing the key name and IP address.
3. Type "yes" and press Enter to confirm.

ssh -i <your key name> ubuntu@<Public IP address>

Step 3: Generate SSL

Run the following command and follow the prompts:

sudo /root/certificate_generate_standalone.sh

Check Server Logs

Step 1: Log in to the server

ssh -i <your key name> ubuntu@<Public IP address>

Step 2: Check the logs

List the running containers, then view the logs of a container using the first few characters of its container ID. Connection problems usually show up in the guacd container, which handles the RDP, SSH and VNC protocols:

sudo docker ps

sudo docker logs <container-id-prefix>

Shutting Down Guacamole

1. In CloudFormation, click the link labeled "Instance" in the "Resources" tab to open the EC2 instance.
2. Stop the Guacamole instance from the Instance state dropdown. You can restart it later as needed.

Remove Guacamole

Delete the CloudFormation stack from the AWS Management Console under "CloudFormation Stacks" by clicking "Delete".

Upgrades

When a new version is available in AWS Marketplace, remove the previous deployment after backing up necessary server data, and relaunch with the new version.

Troubleshoot

If you face vCPU quota limits, request an increase: How to increase AWS quota.

If you face insufficient capacity errors while creating the stack, try another region or time.

If the dashboard shows a 502 Bad Gateway error, wait 5-10 minutes and retry. Guacamole can take a few minutes to start after the instance boots.

If a saved connection fails to open, check that the target machine's security group allows RDP (3389), SSH (22) or VNC (5900) from the Guacamole instance, then check the guacd container logs as shown above.

Check whether the instance storage is full. Log into the server and run:

df -h

If the root volume is between 90-100%, resize the EBS volume, then reboot and restart the service.

Conclusion

The Meetrix Guacamole Deployment Guide helps you run a browser-based remote access gateway in your AWS environment. Whether you're a DevOps engineer, system administrator, or IT leader, this guide provides step-by-step instructions for a secure setup. See the Apache Guacamole store page for what the Meetrix image includes and how it compares with Teleport. If you are still weighing remote access options, our roundup of the best self-hosted VPNs covers the network-level approach.

Technical Support

Reach out to Meetrix Support (aws@meetrix.io) for assistance with Guacamole issues.