> Source: https://meetrix.io/blogs/guacamole-developer-guide/ > Markdown copy of that page. Cite the URL above, not this file. Development # Apache Guacamole - Developer Guide [By Binuka Ranatunga](https://meetrix.io/blogs/authors/binuka-ranatunga/) • October 12, 2026 • 9 min read 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](https://guacamole.apache.org/) 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](https://meetrix.io/blogs/rustdesk-developer-guide/) covers a self-hosted alternative, and the [OpenVPN developer guide](https://meetrix.io/blogs/openvpn-developer-guide/) shows how to put whole networks behind a VPN instead. Prerequisites Before you get started with the Guacamole AMI, ensure you have the following prerequisites: - Basic knowledge of AWS services, including EC2 instances and CloudFormation. - An active AWS account with appropriate permissions. - An EC2 key pair in the region you will deploy to. - An S3 bucket in the same region for backups. - If you encounter a vCPU quota error when launching the stack, follow [https://meetrix.io/blogs/increase-aws-vcpu-quota/](https://meetrix.io/blogs/increase-aws-vcpu-quota/) to increase your vCPU limit. ## Launching the AMI ### Step 1: Find and Select Guacamole AMI 1. Log in to your AWS Management Console. 2. Navigate to '[Apache Guacamole](https://aws.amazon.com/marketplace/pp/prodview-4n2qioyplj4k2)' 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. ![CloudFormation Parameters list for the Guacamole stack showing AdminEmail, AdminPassword, AmiId for version 1.6.0, DeploymentName, DomainName, InstanceType set to t3a.small, KeyName, S3Bucket, SSHLocation and CIDR blocks](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-01.png) 1. Tick **"I acknowledge that AWS CloudFormation might create IAM resources with custom names"**. 2. Click **"Submit"**. ![CloudFormation capabilities notice for IAM Policy and Role resources with the acknowledgement checkbox ticked](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-02.png) Afterward, you'll be directed to the CloudFormation stacks page. Please wait 5-10 minutes until the stack status shows **CREATE\_COMPLETE**. ![Guacamole CloudFormation stack Outputs tab listing DashboardUrl, DashboardUrlIp and PublicIp](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-03.png) ## Update DNS ### Step 1: Copy IP Address Copy the public IP labeled **"PublicIp"** in the **"Outputs"** tab. ![PublicIp Elastic IP value highlighted in the Guacamole stack Outputs tab](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-04.png) ### 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"**. ![Route 53 Quick create record form with an A record for the Guacamole subdomain](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-05.png) ## 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. Note If you receive a "502 Bad Gateway" error, wait approximately **5 minutes** and refresh the page. Guacamole may still be initializing. On the login screen, enter the username **guacadmin** and the **AdminPassword** you set in the stack parameters, then click **"Login"**. ![Apache Guacamole 1.6.0 login page with the guacadmin username entered](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-06.png) 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](https://guacamole.apache.org/doc/gug/) lists every parameter each protocol supports. Admin account The guacadmin account can see and change every connection. Create a separate, non-admin user for day-to-day access, and give each user only the connections they need. If your team already runs single sign-on, see our [Keycloak developer guide](https://meetrix.io/blogs/keycloak-developer-guide/) for an identity provider you can host on AWS the same way. ## 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. ```plaintext ssh -i ubuntu@ ``` ![Terminal connecting to the Guacamole server over SSH and confirming the host fingerprint](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-07.png) ### Step 3: Generate SSL Run the following command and follow the prompts: ```plaintext sudo /root/certificate_generate_standalone.sh ``` ## Check Server Logs ### Step 1: Log in to the server ```plaintext ssh -i ubuntu@ ``` ![Terminal connecting to the Guacamole server over SSH with a private key](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-08.png) ### 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: ```plaintext sudo docker ps sudo docker logs ``` ## 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. ![CloudFormation Resources tab with the EC2 Instance physical ID link](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-09.png) ![EC2 Instance state dropdown with the Stop instance option](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-10.png) Note Stopping the instance ends every open remote session. The machines behind Guacamole keep running, but users cannot reach them through the browser until the instance is started again. ## 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](https://meetrix.io/blogs/increase-aws-vcpu-quota/). ![CloudFormation event showing CREATE\_FAILED with a VcpuLimitExceeded error](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-11.png) If you face _insufficient capacity_ errors while creating the stack, try another region or time. ![CloudFormation event showing CREATE\_FAILED with an InsufficientInstanceCapacity error](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-12.png) 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. ![502 Bad Gateway error page served by nginx](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-13.png) 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: ```plaintext df -h ``` ![df -h output showing usage of the root filesystem](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-14.png) If the root volume is between 90-100%, [resize the EBS volume](https://docs.aws.amazon.com/ebs/latest/userguide/requesting-ebs-volume-modifications.html), 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](https://meetrix.io/store/guacamole/) 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](https://meetrix.io/blogs/best-self-hosted-vpn/) covers the network-level approach. ## Technical Support Reach out to Meetrix Support ([aws@meetrix.io](mailto:aws@meetrix.io)) for assistance with Guacamole issues. ## Frequently Asked Questions What is Apache Guacamole? Apache Guacamole is an open-source, clientless remote desktop gateway. It lets you reach machines over RDP, VNC, SSH, Telnet and Kubernetes from a web browser, with no plugin or desktop client installed on the user's device. What are the login details for the Guacamole dashboard? Log in with the username guacadmin and the AdminPassword you set in the CloudFormation stack parameters. Store the password securely, since it is the administrator account for every connection you add. Which instance type is recommended? t3a.small is the recommended baseline. Guacamole itself is light, but each active remote session uses CPU and memory on the gateway, so choose a larger instance if many users will connect at the same time. What is the S3Bucket parameter used for? It is an S3 bucket in your account that the instance uses to store backups. Create the bucket before launching the stack, in the same region. Can I use Guacamole as a bastion host for private EC2 instances? Yes. Add connections that point at the private IP addresses of instances in the same VPC, or in a peered VPC, and allow RDP, SSH or VNC traffic to them from the Guacamole instance's security group. Users then reach those machines through the browser without the instances having public IPs. How do I upgrade Guacamole? When a new version is available in AWS Marketplace, back up the data you need, remove the previous deployment, then launch a new stack with the new version. How do I get technical support? Reach out to Meetrix Support at [aws@meetrix.io](mailto:aws@meetrix.io) for assistance with Guacamole issues. ## Ready to Deploy Your Own Guacamole Gateway? Get started in minutes with our pre-configured AMI and reach your desktops and servers from any browser. [Deploy Apache Guacamole from AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-4n2qioyplj4k2) Meetrix Store Apache Guacamole RDP, SSH and VNC from any browser, no client to install [Deploy it](https://meetrix.io/store/guacamole/) Meetrix Store New Deploy what this guide covers, pre-configured. - [Apache Guacamole RDP, SSH and VNC from any browser, no client to install](https://meetrix.io/store/guacamole/) - [RustDesk Remote desktop AMI, a TeamViewer alternative](https://meetrix.io/store/rustdesk/) - [OpenVPN Encrypted remote access, no per-user fees](https://meetrix.io/store/openvpn/) - [Jitsi Meet Self-hosted video calls for 50 to 500 users](https://meetrix.io/store/jitsi-meet/) - [Coturn TURN/STUN for WebRTC, no per-minute relay fees](https://meetrix.io/store/coturn/) - [Supabase Postgres, Auth, Storage and Realtime, self-hosted](https://meetrix.io/store/supabase/) [Browse all products](https://meetrix.io/store/)