How to Setup Apache Guacamole on a Raspberry Pi!

  • Post author:
  • Post last modified:November 2, 2022
  • 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!

Please share if this helped you!


IT professional and creator of WunderTech. Passionate about NAS, Docker, virtualization, firewalls, self-hosted apps, and an avid home lab enthusiast.
You are currently viewing How to Setup Apache Guacamole on a Raspberry Pi!

This Post Has 25 Comments

  1. 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

  2. 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!

  3. 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?

  4. 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.