Creating a Remote Desktop Web Gateway on Raspberry Pi with Apache Guacamole


Last Updated on 6th February 2022 by peppe8o

Smart Working needs are stressing the needs to have an external access to your Personal Computer from a remote station. This remote station can be whatever device, with whatever OS (and different versions). The very first need for people is remoting their Desktop to have access their docs and apps.

A flexible solution comes with Apache Guacamole™, an Open Source software able to give a clientless remote desktop access (via VNC, RDP, SSH, etc). This solution differs from common ones because it can be used from a simple Web Browser, helping to overcome client installation issues.

This guide will provide step-by-step procedure to install Apache Guacamole in your Raspberry PI, making it your personal remote desktop web gateway. Also Docker will be user to simplify service setup.

Network Diagram

First of all, let me show a simple diagram to better understand what we are building.

Apache Guacamole RPI network diagram_v2

This solution requires that:

  • Your Raspberry PI can be reached from your laptop from where you want to see remote desktop
  • Your remote PC have RDP configured or VNC server active or SSH remote connection enabled

In this post, I’m going to use a Windows RDP connection. A remote Windows 10 PC will be managed by an external device (maybe another PC with different OS, a tablet, etc).

What We Need

As usual, I suggest adding from now to your favourite e-commerce shopping cart all the needed hardware, so that at the end you will be able to evaluate overall costs and decide if to continue with the project or remove them from the shopping cart. So, hardware will be only:

Raspberry PI 3 Model B+ image

Check hardware prices with following links:

Amazon raspberry pi boards box
Amazon Micro SD box
Amazon Raspberry PI Power Supply box

Step-by-Step Procedure

Configure RDP on remote PC

Remote PS with Windows OS must be configured to accept connections from specified users already created. With Windows 7, users are usually belonging to Workgroup or specific domain, having a specific password. With Windows 8 / 10, users will usually match with mail address and related password. In both cases you must configure your user to belong in Remote Desktop Users group.

Note that you can’t connect to a computer that’s asleep or hibernating. Make sure settings for sleep and hibernation on remote computer are set to Never in Energy Management options.

Configure RDP on remote PC in Windows 7

For Windows 7 Remote PCs, the procedure can be found in

  1. Open System by clicking Start button, right-clicking Computer, and then clicking Properties.
  2. Click Remote settings.  If you’re prompted for an administrator password or confirmation, type the password or provide confirmation. Under Remote Desktop, select one of the three options.
  3. Click Select Users.

If you’re a computer administrator, your current user account will automatically be added to the list of remote users and you can skip next two steps.

  1. In Remote Desktop Users dialog box, click Add.
  2. In Select Users or Groups dialog box, do following:
    • To specify search location, click Locations, and then select the location you want to search.
    • In Enter the object names to select, type user name that you want to add, and then click OK.

The name will be displayed in user list of Remote Desktop Users dialog box. Click OK, and then click OK again.

Configure RDP on remote PC in Windows 8 / 10

For Windows 8 / 10 Remote PCs, procedure can be found in

  1. On device you want to connect to, select Start and then click Settings icon on left.
  2. Select System group followed by Remote Desktop item.
  3. Use the slider to enable Remote Desktop.
  4. It is also recommended to keep PC awake and discoverable to facilitate connections. Click Show settings to enable.
  5. As needed, add users who can connect remotely by clicking Select users that can remotely access this PC.

Members of Administrators group automatically have access.

Install Raspberry PI OS Lite Operating System

Start installing Raspberry PI Os Lite as operating system.

Take note of your Raspberry PI IP address, that will be referred in this post as << YourRpiIpAddress >>.

Install Docker

Also for this part, please use Setup a Docker Environment with Raspberry PI OS Lite and Portainer article. Portainer is a simple and useful web GUI for docker, but its installation is optional for our purpose.

Run Guacamole Container

With Docker, runnung a Guacamole service is particularly easy.

Guacamole container is not ready AS-IS to run on Raspberry PI: it is built on AMD / Linux architecture. Our Raspberry PI, on the other hand, is an ARM architecture.

An help comes from Oznu/docker-guacamole image. With this, once connected to your Raspberry PI via SSH terminal, container can be setup with a simple one line command:

docker run -d -p 8080:8080 -v guacamole_config:/config oznu/guacamole:armhf

This will download required packages, setup a container (with config files mapped to a persistent volume) and make it running.

After container is running, please it a minute to have processes ready and running.

Configure Guacamole Connection

Now all operations will be done from the device / PC from which we want to viasualize web Remote Desktop.

Connect from browser to Guacamole login page of your Raspberry PI. Use the URL “http://<<YourRpiIpAddress>>:8080”

Apache Guacamole RPI login

Login with default Guacamole user:

  • USERNAME: guacadmin
  • PASSWORD: guacadmin

From guacadmin user dropdown menu click on “Settings”:

Apache Guacamole RPI login (1)

In next page, click on “Connections” tab:

Apache Guacamole RPI login (2)

In next page, use “New Connection” button to configure a new connection:

Apache Guacamole RPI connections

Next page will let you configure a wide number of parameters to manage your connection type. For a basic Windows RDP connection, you must configure at least the following.

In EDIT CONNECTION section, please enter the name used to refer this connection in you Guacamole Home page (in my example “ASUS”). You can leave Location as ROOT. Please modify Protocol to “RDP”:

Apache Guacamole RPI RDP Conf (1)

In “NETWORK” block, add Hostname parameter with your remote PC IP Address (“” for my example). Port must be set to 3389 (default Windows RDP port).

In “AUTHENTICATION” section, you must enter user and password configured in your remote PC as enabled Remote Users. My remote PC OS is Windows 10, so my username is my mail address with entire mail domain (for example “[email protected]”). In this case, what is after @ becomes also the Domain (and it is not required to edit “Domain” parameter). If you have a local user, you should also include the domain (for example WORKGROUP of whatever is your).

“Security mode” must be set to “Any”. You must also set “Ignore server certificate” flag.

Apache Guacamole RPI RDP Conf (2)

Scroll down this page to bottom and click Save button. Our new connection now appears in Connections list. Use this page only to edit available connections or to create new ones.

Apache Guacamole RPI RDP Conf (3)

Use drop down menu under guacadmin user to go back Home page, where you will find your link to remote desktop connection. Click this link to load your remote desktop.

Apache Guacamole RPI RDP Conf (4)

Final Notes

Remote Desktop to a Windows PC will automatically logout people using Remote PC. In the same way, if you try to launch Remote Desktop to the same PC where you are working, you will be logged out.

Apache Guacamole is plenty of interesing features, try them to find solution that best fit your needs.

I was expecting from this installation better performances from what I obtained with my Raspberry PI 3 Model B (in terms of readyness to commands). Maybe that some setting have to be tuned or a different protocol could perform better.


How useful was this post?

Click on a star to rate it anonymously!

Average rating 4.7 / 5. Vote count: 3

No votes so far! Be the first to rate this post.

We are sorry that this post was not useful for you!

Let us improve this post!

Tell us how we can improve this post?