> Source: https://meetrix.io/blogs/guacamole-gcp-developer-guide/ > Markdown copy of that page. Cite the URL above, not this file. Development # Apache Guacamole on GCP - Developer Guide [By Binuka Ranatunga](https://meetrix.io/blogs/authors/binuka-ranatunga/) • October 15, 2026 • 9 min read Welcome to the Meetrix Apache Guacamole developer guide for Google Cloud Platform! [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. The Meetrix GCP image runs Guacamole with PostgreSQL behind an Nginx reverse proxy with automated SSL, so you get a working gateway in your own GCP project in minutes. This guide walks you through finding the product on GCP Marketplace, configuring the deployment, pointing DNS, logging in for the first time, and managing the server. For what the image includes and how it compares with Teleport, see the [Apache Guacamole store page](https://meetrix.io/store/guacamole/). If you would rather give each user a desktop client, our [RustDesk on GCP developer guide](https://meetrix.io/blogs/rustdesk-gcp-developer-guide/) covers a self-hosted alternative, and the [OpenVPN on GCP developer guide](https://meetrix.io/blogs/openvpn-gcp-developer-guide/) shows how to put a whole network behind a VPN instead. ### Related Article [ Apache Guacamole - Developer Guide (AWS) Step-by-step guide for deploying Apache Guacamole on AWS using the Meetrix pre-configured AMI and CloudFormation. Meetrix.IO • Binuka Ranatunga ![Apache Guacamole developer guide for AWS thumbnail](https://meetrix.io/blog-images/paas-dev-guides/guacamole/guacamole-image.png)](https://meetrix.io/blogs/guacamole-developer-guide/) Prerequisites Before you begin, make sure you have the following: - Basic Google Cloud Platform knowledge. - An active Google account with a GCP project and billing enabled. - A domain name you can manage DNS records for. ## Launch Guacamole from GCP Marketplace ### Step 1: Find the Product 1. Log in to your Google account. 2. Go directly to the product page: [Apache Guacamole Remote Desktop Gateway on GCP Marketplace](https://console.cloud.google.com/marketplace/product/meetrix-public/guacamole) 3. You can also browse all Meetrix products at the [Meetrix Solutions Page](https://console.cloud.google.com/marketplace/browse?filter=partner:Meetrix%20Pte%20Ltd&ref=meetrix.io). 4. You will see the following product listing page. Click **Launch**. ![Apache Guacamole Remote Desktop Gateway: Browser RDP, VNC, SSH listing on GCP Marketplace by Meetrix Pte Ltd, showing the 5-day trial badge and the Launch button](https://meetrix.io/blog-images/paas-dev-guides/guacamole-gcp/guacamole-gcp-1.png) ### Step 2: Accept the Agreement 1. Select your GCP project from the project selector at the top. 2. Tick the terms and agreements checkbox. 3. Click **AGREE**. ![GCP Marketplace agreements screen with the project selector, the terms checkbox ticked, and the AGREE button](https://meetrix.io/blog-images/paas-dev-guides/guacamole-gcp/guacamole-gcp-2.png) ### Free Trial This product includes a **5-day free trial** with up to USD 50.00 in licence fee credits. To activate it, tick **I accept the solution trial Terms and Conditions** at the bottom of the deployment form before you click Deploy. ![Checkbox to accept the Apache Guacamole solution trial Terms and Conditions on GCP](https://meetrix.io/blog-images/paas-dev-guides/guacamole-gcp/guacamole-gcp-3.png) Trial note Infrastructure charges (VM, disk) still apply during the trial. Only the Meetrix licence fee is credited. You can cancel the trial at any time by deleting the deployment. ## Configure Your Guacamole Deployment on GCP You will see the deployment configuration form. Fill in the fields across the following sections: ![New Apache Guacamole Remote Desktop Gateway deployment form on GCP showing the deployment name guacamole-1, an existing deployment service account, the zone us-central1-a, the e2-small machine type, and the product trial terms](https://meetrix.io/blog-images/paas-dev-guides/guacamole-gcp/guacamole-gcp-4.png) ### General - **Deployment name**: A unique name for this deployment. - **Deployment Service Account**: Use an existing account that has the `roles/config.agent`, `roles/compute.admin` and `roles/iam.serviceAccountUser` roles, or create a new one. - **Zone**: Select the GCP zone closest to your users, or to the machines Guacamole will connect to. - **Machine type**: The default `e2-small` (2 vCPU, 2 GB memory) handles a small team. Go larger if many users will hold remote sessions at the same time. ### Networking - **Network / Subnetwork**: Leave as `default` unless you have a custom VPC. Choose the VPC that holds the machines you want to reach, so Guacamole can connect to them over their internal IPs. - **External IP**: Leave as `Ephemeral` so users can reach the dashboard from the internet. - **Allow SSH (TCP port 22)**: Enabled by default. Restrict the source IP range if you want to limit SSH access to specific IPs. ![Guacamole GCP networking settings with the default network and subnetwork, an Ephemeral external IP, and SSH allowed from 0.0.0.0/0](https://meetrix.io/blog-images/paas-dev-guides/guacamole-gcp/guacamole-gcp-5.png) ### Application Settings - **Domain name**: The domain for your Guacamole server (e.g. `guacamole.yourdomain.com`). Point your DNS A record to the instance IP before or shortly after deploying. - **Admin email**: Used for SSL certificate registration via Let's Encrypt. - **Admin password**: The password for the **guacadmin** account you log in with. Store it securely. ![Lower half of the Guacamole GCP deployment form with the firewall settings, API access, and the Application Settings fields for domain name, admin email and admin password, above the trial checkbox and the Deploy button](https://meetrix.io/blog-images/paas-dev-guides/guacamole-gcp/guacamole-gcp-6.png) Click **Deploy** and wait a few minutes for the deployment to complete. ## Point DNS to Your Guacamole Server ### Step 1: Get the External IP 1. Once deployment is complete, click the VM instance resource name in the deployment details. 2. Copy the **External IP** from the Network interfaces section. ![Network interfaces section of the GCP VM instance showing the internal IP and the ephemeral external IP address](https://meetrix.io/blog-images/paas-dev-guides/guacamole-gcp/guacamole-gcp-7.png) ### Step 2: Create a DNS A Record 1. Go to your DNS provider. 2. Add an **A record** pointing your Guacamole domain (e.g. `guacamole.yourdomain.com`) to the copied external IP. 3. Wait for DNS propagation before proceeding (typically a few minutes to 1 hour). DNS must propagate first The image issues SSL via Let's Encrypt, which verifies domain ownership over HTTP. Make sure your DNS A record points to the server IP and has propagated before the certificate request runs. ## Access Guacamole Once DNS has propagated and SSL has been issued, visit your domain. On the login screen, enter the username **guacadmin** and the **Admin password** you set in the Application Settings, then click **Login**. ![Apache Guacamole 1.6.0 login page with Username and Password fields, served on a custom domain](https://meetrix.io/blog-images/paas-dev-guides/guacamole-gcp/guacamole-gcp-9.png) 502 Bad Gateway Error? If you see a "502 Bad Gateway" error, Guacamole is still starting up. Wait about 5 minutes and refresh the page. After login you land on the Guacamole home page. It lists **Recent Connections** and **All Connections**, both empty on a fresh deployment. ![Guacamole home page logged in as guacadmin, with empty Recent Connections and All Connections lists](https://meetrix.io/blog-images/paas-dev-guides/guacamole-gcp/guacamole-gcp-10.png) ### Add Your First Connection Open the **guacadmin** 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 IP address and its credentials, and save. The connection then appears on the home page for every user you grant it to. The [Guacamole manual](https://guacamole.apache.org/doc/gug/) lists every parameter each protocol supports. For VMs in the same VPC, use their **internal IP**. Those VMs then do not need an external IP at all, which is what makes Guacamole a good bastion host on GCP. Allow the traffic with a [VPC firewall rule](https://cloud.google.com/firewall/docs/using-firewalls) from the Guacamole VM to the targets on the ports they use: RDP (3389), SSH (22) or VNC (5900). 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 yourself. ## Generate an SSL Certificate for Guacamole Manually Guacamole automatically tries to issue SSL for the domain name you provided during deployment. If that fails, for example because DNS had not propagated yet, generate it manually. ### Step 1: SSH into the Server 1. Go to the VM instance page in the GCP console. 2. Click **SSH** to open a browser-based terminal and authorize access. ![GCP VM instance details page with the SSH button at the top](https://meetrix.io/blog-images/paas-dev-guides/guacamole-gcp/guacamole-gcp-8.png) ### Step 2: Run the Certificate Script The image includes a pre-configured certificate script. Run it with: ```bash sudo bash /root/certificate_generate_standalone.sh ``` This script runs certbot using the domain name and admin email you provided during deployment. ## Check Guacamole Server Logs SSH into the server as shown above. 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: ```bash sudo docker ps sudo docker logs ``` Nginx sits in front of Guacamole and terminates SSL. If the dashboard does not load at all, check it too: ```bash sudo systemctl status nginx ``` ## Manage Your Guacamole Deployment on GCP ### Shut Down the VM To stop the VM without deleting it, go to **Compute Engine → VM Instances** in the GCP console, select your instance, and click **Stop**. You can restart it later by clicking **Start/Resume**. Note Stopping the VM ends every open remote session. The machines behind Guacamole keep running, but users cannot reach them through the browser until it is started again. ### Delete the Deployment To fully remove the deployment and stop all billing: 1. Go to **[Solution deployments](https://console.cloud.google.com/products/solutions/deployments)** in the GCP console. 2. Find your Guacamole deployment. 3. Click **Delete** to remove all associated resources. ### Upgrades When there is an upgrade, we update the product with a newer version. You can check the product version in GCP Marketplace. If a newer version is available, back up your server data, delete the current deployment, and launch the product again using the newer version. ## Troubleshoot Guacamole on GCP ### Insufficient Capacity Error If you see an error stating there is not sufficient capacity for the selected machine type while deploying, try a different zone or try again later. ### 502 Bad Gateway If you see a 502 Bad Gateway error when accessing your domain, Guacamole is still starting up. Wait 5-10 minutes and try again. If it persists, check the container status and logs as shown above. ### A Connection Fails to Open If a saved connection fails, check that a VPC firewall rule allows RDP (3389), SSH (22) or VNC (5900) from the Guacamole VM to the target, and that the hostname or IP in the connection is correct. Then check the guacd container logs as shown above. ### Storage Full Error Container images, database data and logs can fill the boot disk over time. If the dashboard becomes unresponsive, SSH into the server and run: ```bash df -h ``` If the root volume is between 90-100%, [resize the boot disk](https://cloud.google.com/compute/docs/disks/resize-persistent-disk) from the Compute Engine console, then reboot the instance. ## Conclusion You now have a self-hosted Apache Guacamole gateway running in your own GCP project, with SSL and your own domain. From here, add connections to your servers and desktops, create non-admin users, and keep the target VMs on internal IPs behind it. 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 If you run into any issues, our support team is here to help. Reach out to us at [support@meetrix.io](mailto:support@meetrix.io) and we will respond within 12 hours. ## 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 and Telnet 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 Admin password you set in the Application Settings section of the deployment form. Store the password securely, since it is the administrator account for every connection you add. Which machine type should I choose for Guacamole on GCP? The default e2-small (2 vCPU, 2 GB memory) is enough for a small team. Guacamole itself is light, but each active remote session uses CPU and memory on the gateway, so choose a larger machine type if many users will connect at the same time. Can I use Guacamole as a bastion host for private Compute Engine VMs? Yes. Add connections that point at the internal IP addresses of VMs in the same VPC network, and add a VPC firewall rule that allows RDP, SSH or VNC traffic to them from the Guacamole VM. Those VMs then need no external IP, and users reach them through the browser. Is there a free trial? Yes. The Meetrix Guacamole listing includes a 5-day free trial with up to USD 50.00 in licence fee credits. Infrastructure charges for the VM and disk still apply during the trial. How do I upgrade Guacamole? When a newer version is available in GCP Marketplace, back up the data you need, delete the current deployment, and launch the product again with the new version. How do I get technical support? Reach out to Meetrix Support at [support@meetrix.io](mailto:support@meetrix.io) for help with the Guacamole GCP deployment. ## Deploy Apache Guacamole on GCP in Minutes Launch a production-ready Apache Guacamole gateway on Google Cloud with a pre-configured Meetrix image and reach your desktops and servers from any browser. [Get Started on GCP Marketplace](https://console.cloud.google.com/marketplace/product/meetrix-public/guacamole) 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/) - [Listmonk Newsletters with no per-subscriber fees](https://meetrix.io/store/listmonk/) [Browse all products](https://meetrix.io/store/)