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.
2. Enter the name as Guacamole and then create the volume.
3. Go to Containers and Add Container.
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.
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!
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.
http://[RASPBERRY_PI_IP]:[PORT]
7. When you access the landing page, log in with the username guacadmin and password guacadmin.
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.
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.
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.
2. Give your group a name, modify any settings you’d like, and select Save.
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.
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.
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.
2. At the bottom, select Env and add an environment variable.
3. Enter EXTENSIONS in the name and auth-totp in the value.
4. Select Deploy the container. The container will now redeploy and when you login, you will be asked to set up two-factor authentication!
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!
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.
Glad you got it working and thanks for the input!
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.
Are you using Synology’s firewall? If so, can you disable it temporarily to see if it connects?
Hi,
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
Glad you got it working!
Hi.
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
Hey,
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 😉
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.
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
Awesome! Yes, the latest release was on February 6th!
No such image. Is the image no longer there? I looked at the project in github and it’s been achived.
Thanks!
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!
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!
Hey,
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
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.
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!
Not a problem, glad to hear you got it working!
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?
Are you using a firewall on the Raspberry Pi? Also, is the container running properly? Let me know and we can continue troubleshooting!
Hi
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
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!
Further: Port of VNC server is open:
sudo telnet 192.168.0.17 5900
Trying 192.168.0.17…
Connected to 192.168.0.17.
Guacamole says:
The remote desktop server is currently unreachable. If the problem persists, please notify your system administrator, or check your system logs.
Hi
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 :
GUACAMOLE PROXY PARAMETERS (GUACD)
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.
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!