How to Setup Apache Guacamole on a Raspberry Pi!

  • Post author:WunderTech
  • Post published:October 4, 2020
  • Post last modified:October 30, 2023
  • Post category:Raspberry Pi
  • Reading time:11 mins read

Today we are going to look at how to install Apache Guacamole on a Raspberry Pi.

Apache Guacamole is a clientless remote desktop gateway that runs in your browser. In summary, you’re able to RDP, VNC, or SSH into devices on your network through a web browser. You can also setup Telnet and Kubernetes, but we won’t be going over that in this tutorial. The tool works very well and allows you to manage all your connections in a centralized location accessible by a web browser.

It is my recommendation that you use a Raspberry Pi 4 when using Guacamole since it supports gigabit ethernet. This will work on all Raspberry Pi devices, but the network bandwidth is what will ultimately limit you when using older devices.

We will set this up by using Docker and Portainer, so if you haven’t set that up yet, please check out my tutorial here.

If you’d like to learn about the Apache Guacamole Docker container or install it without using Portainer, you can find the github page here.

1. Instructions – Raspberry Pi Apache Guacamole

1. First, we are going to create a volume in Portainer. Open Portainer and select Volumes. Then, select Add Volume.

portainer volumes section

2. Enter the name as Guacamole and then create the volume.

raspberry pi apache guacamole container setup

3. Go to Containers and Add Container.

raspberry pi apache guacamole - selecting containers to add a new one

4. Enter the name as Guacamole and under image, enter oznu/guacamole:armhf. Select Publish a new network port and enter 8080 for both the host and container. NOTE: If you are using port 8080 for anything else, you can use a different port.

raspberry pi apache guacamole creation process with name, container, and port

5. At the bottom, select Volumes and then map additional volume with the path as /config and the volume that we created earlier. Select Restart Policy and change the restart policy to Always. You can then deploy the container!

raspberry pi apache guacamole - volume creation
container restart always policy

6. The image will now download and then install. You will need to give this upwards of 5-10 minutes for the entire process to finish. When it does, you can navigate to Apache Guacamole by your Raspberry Pi’s IP address and port 8080.


7. When you access the landing page, log in with the username guacadmin and password guacadmin.

raspberry pi apache guacamole login page

8. The first thing we will do is create a new username and delete guacadmin. In the top right, select guacadmin and then settings. Select Users and then New User.

raspberry pi apache guacamole setting section to add a new user

9. Create a new user and save. NOTE: There are a bunch of different options here that you can tinker with if you’d like.

raspberry pi apache guacamole - user profile

10. Logout and then log in with your newly created user. Navigate to the settings and then delete the guacadmin user.

11. The setup process is now complete!

2. Remote Connection Setup

Setting up a remote connection is super simple. The key is to ensure that the destination device (Windows, Mac, Linux PC) is configured properly. Generally, you will be using RDP or VNC sessions if you’d like to view the desktop of a destination PC and SSH if you’d like to connect to the terminal. I’m not going to go over each example, but I will go over the general way of adding a new group and connection.

2.1 How to Create a Connection Group

Groups give you an easy way of structuring your machines. This will need to be created based on your requirements, but I generally split my machines up by category (Windows, Linux).

1. Navigate to the settings and select Connections, then New Group.

creating groups in apache guacamole

2. Give your group a name, modify any settings you’d like, and select Save.

connection group settings

2.2 How to Create a New Connection

Connections are what you’ll use to connect to your machines. I am not going to give specific examples but will show you how you can create RDP, VNC, or SSH connections.

1. Navigate to the settings and select Connections, then New Connection.

creating a new connection in apache guacamole

2. Enter a Name and then select Location to pick a group. Under Protocol, select RDP, VNC, or SSH.

3. There are a ton of settings here, but simply entering the information in the Parameters section will allow you to connect. Add your Hostname and port (3389 for RDP, 5900 for VNC, 22 for SSH). Then add your Username and Password to the destination device and save the connection. There are a ton of other options that can be changed, but in general, these are the most important.

adding a new device to apache guacamole

2.3 Multi-Factor Authentication

There are many reasons why someone would want to expose Apache Guacamole to the outside internet. Generally, it’s suggested that rather than exposing the service, you use a VPN to tunnel back to your home network. However, if you want to expose this to the internet, you can use Nginx Proxy Manager, set up an SSL certificate, and enable two-factor authentication on Guacamole. To enable two-factor authentication, follow these steps.

1. Open Portainer, navigate to the container, and select Duplicate/Edit.
how to stop apache guacamole container
2. At the bottom, select Env and add an environment variable.

portainer environment variables

3. Enter EXTENSIONS in the name and auth-totp in the value.

adding the extensions environment variable

4. Select Deploy the container. The container will now redeploy and when you login, you will be asked to set up two-factor authentication!

editing multi-factor authentication in apache guacamole

3. Conclusion – Raspberry Pi Apache Guacamole

Apache Guacamole is an awesome little tool and it’s super easy to setup on a Raspberry Pi. It’s very nice to be able to manage remote connections in a central location and it’s great that it works on all devices with a web browser! I’ve always used remote desktop connection tools but it was an entire setup every time I’d like to implement it on a new device. This is an easy way to hit all of your devices at the same time!

If you have any questions, please leave them in the comments. Thanks for reading!


Frank is an IT professional with 13+ years experience and the creator of WunderTech. He focuses on sharing his experience with others on computer hardware, servers, software, networking, and self-hosted apps. He has a BS in Computer Information Systems and an MBA. Learn more about Frank in his bio.

This Post Has 25 Comments

  1. jørgen


    Thank you for the guide on RaspBerry Pi using Guacamole..

    I am not able to connect to a RaspBerry PI via VNC.

    How to set up :


    Can you provide eloborate ?

    From the Dockerfile i do not see the ¨proxy GUACD as part of the image oznu/guacamole:armhf

    I suppose the VNC webserver must be loaded using port 5900. Any further requirement ?

    Thank you in advance.

    1. WunderTech

      When you say that you can’t connect to it via VNC, did you configure the Raspberry Pi to accept VNC connections? Have you tried to connect via SSH and does that work?

      Let me know and we can continue troubleshooting!

  2. jørgen

    Further: Port of VNC server is open:
    sudo telnet 5900
    Connected to

    Guacamole says:
    The remote desktop server is currently unreachable. If the problem persists, please notify your system administrator, or check your system logs.

  3. jørgen


    Thank you for your efforts.
    The error is on my side.

    Under “Security” on the VNC graphical interface on RaspBerry PI “VNC password” MUST be chosen….

    UNIX does not work…

    …Good to know…

    Feel free to comment on my draft homepage…. the site is NOIP based…last day today or tomorrow

    1. WunderTech

      I’m glad to hear that you figured out what the issue was. Sorry that I didn’t see this in time! Good luck with the new site!

  4. Woife

    Hello I am new to docker. After Step 6 I can not connect to the webview. The host rpi is listening to the right socket, aswell as the docker container (I checked via terminal of that container). I also tried setting “iptables”:true in the /etc/docker/key.json with no succes. What could be the reason?

    1. WunderTech

      Are you using a firewall on the Raspberry Pi? Also, is the container running properly? Let me know and we can continue troubleshooting!

  5. Woife

    Your quick response is highly appreciated! I feel totally stupid because it seemed that a local appache webserver instance blocked the port 8080. When I shut down the instance it worked. The sad thing is, that I tested at first with a different port on the rpi (5123) to map on 8080 in the container but this also did not work. That’s why I at first thought it could not be apache webserver.
    Anways it works now like a charm thank you for the tutorial!

    1. WunderTech

      Not a problem, glad to hear you got it working!

  6. Sam


    Just wanted to ask you how your performance experience has been with guacamole running in that docker on the Raspberry. Because for me the experience has been… Less than stellar. Even just using SSH to the container itself and scrolling the terminal (admittedly a fancy terminal with powerline10k theme and displaying the output of exa, a more colerful ls, ~35 lines) my Raspberry pi 4 stutters and Java combined with guacamole take up ~ 90% of the CPU. I can’t even think of I. E. A RDP connection to my Windows PC on the same LAN using a 3rd device.

    I admit my setup is somewhat complicated but I don’t think it’s supposed to be quite so problematic. And trying to find the issue is quite infuriating with these eternal 5 minutes setup time the container needs on every restart.

    Add to that that I’m no expert in how VNC/RDP or even SSH work technically and what common performance issues might be, and I’m lost.

    So for that reason, if you have tried a few different things and could comment on their performance I’d greatly appreciate it.

    Regards, Sam

    1. WunderTech

      When I was running it on my Raspberry Pi, the performance was fine. I wouldn’t say it was great, but it was certainly good enough to use the tool. I didn’t experience any of the issues you stated. However, there’s very little difference between the performance on my Raspberry Pi and my current setup on my Synology NAS. Overall, it’s just a basic web server running VNC/RDP/SSH, so you don’t need the beefiest of specs to get it working well.

      Are you running anything else on your Pi? Is the Java running on the same Pi, and if so, is the performance low when Guacamole isn’t installed?

      If I’m being honest, performance is a very difficult thing to troubleshoot since everyone’s setup’s are generally different, but if you’re running a Pi 4 with 4GB of memory (that’s what I have, 8GB would be better but most likely unnecessary), it should run fine.

  7. Sam


    I usually a number of things on that Pi, I. E. Nextcloud, codercom/code-server, bitwardenrs, amir20/dozzle, linuxserver/heimdall, linuxserver/wireguard, nicolelargo/glances. And these services are behind a traefik reverse proxy, sometimes connected with LDAP and use Authelia as SSO.

    But still in idle CPU usage is usually below 10% and these services just take up RAM. And my Pi is pretty much best case for performance elsewise, it’s a 8GB variant with a finned metal case for cooling and the OS is running on an SSD.

    I don’t think that the background-tasks were making issues in this test, I’ve in fact tried it without them too and the same issue. That “Java” process im talking about is spawned by the Guacamole container.

    I guess it comes down to any of the other things:

    * traefik setup
    * I run my containers with cut down privileges, maybe that causes some fallback that eats performance.
    * maybe some strange thing caused by the fact that I’m running this on Manjaro and not a more traditional Debian based linux
    * some problematic config on any of the PCs used

    I guess I’m gonna do some testing with only the guacamole container with a simple port-forward. Don’t know why I’ve not done that from the start, was stupid trying something else.

    If it still won’t work I guess I’ll just drop back to wetty (a simpler SSH webclient) and not have fancy VNC and RDP.

    But still, thanks, knowing that it’s not the container is a great help!

    1. WunderTech

      Not a problem! You certainly have a unique setup, but that’s a good thing! Goes to show you’re utilizing the Pi the best way you can.

      Unfortunately, due to the setup, there are various things it could be and testing is the only way to try and isolate the high CPU usage, but it sounds like you’re on the right track!

  8. Mike

    No such image. Is the image no longer there? I looked at the project in github and it’s been achived.

  9. Mike

    I finally managed to install it. I had a period not a colon before the “armhf” in “oznu/guacamole:armhf”. It’s up and running. Is it being updated by the docker container creator? Thanks

    1. WunderTech

      Awesome! Yes, the latest release was on February 6th!

  10. Thecrafterja

    thanks for the tutorial.
    I have a problem: I am using a Raspberry PI 4 Model B with 4 gigs of RAM. The OS is Raspbian Lite and the only changes I have done were installing docker, Portainer and Guacamole.
    If I connect via RDP, Portainer shows a CPU Usage of 100% and sometimes 200% and the connection is very laggy.

    Do you have any advice?

    Thanks for all the tutorials.

    Disclaimer: Sorry for my bad English 😉

    1. WunderTech

      Are you running any other containers? Apache Guacamole shouldn’t impact the CPU that much, so there might be something else running on the device.

  11. Vladimir

    I’m kinda stuck at step 6. If I use the port 8080, I can connect to the guacamole web interface, but if I use another port in the container, I get an error and can’t connect to the web interface. Btw, I’m running raspberry pi 4 with 8GB and raspberry pi os lite. I haven’t configured any firewalls, except if there is an active firewall by default.
    Help would be appreciated

  12. Vladimir

    guess I had to write a comment in order to solve my issue. The problem was I had to change the host port, and not the container port. Anyway, love your tutorials. THX

    1. WunderTech

      Glad you got it working!

  13. frankie

    So after following these 2 tuts on installing docker and portainer. the docker seems to be running, I can connect to portainer webview but get a timed out when trying to connect to guacamole. Not exactly sure at this point.

    1. WunderTech

      Are you using Synology’s firewall? If so, can you disable it temporarily to see if it connects?

  14. John

    This is pretty awesome, thanks! I’m running it on an 8gig Ras Pi 4 with the beta 64 bit RPI OS (I’m also using arm64 Docker). The oznu/guacamole:armhf image did not work at all well but maxwaldorf/guacamole (arm64v8) works fantastic. VNC scrolling has a very slight lag but it’s totally usable! I finally figured out I had to export my ssh private keys in OpenSSH format from PuttyGen and paste them in to get secure ssh working.

    1. WunderTech

      Glad you got it working and thanks for the input!

Comments are closed.