# Guacamole's superproject, one mvn package, and a .war you deploy yourself

> guacamole-client is the Apache Guacamole superproject: a Maven aggregator that builds a browser-based remote desktop gateway into a .war for Tomcat or Jetty. Building it is easy; running it means owning a servlet container and a database behind it.

**apache/guacamole-client** — The Apache Guacamole web application, official extensions, and JavaScript library.

- Repository: https://github.com/apache/guacamole-client
- Website: https://guacamole.apache.org/
- Stars: 1,742 · Forks: 861
- Language: Java
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/apache-guacamole-client

## What the superproject actually is

The name is misleading if you read it as "the Guacamole application". The README describes guacamole-client as a superproject containing all Maven-based projects that make up Apache Guacamole, an HTML5 web application that gives you access to a desktop over remote desktop protocols.

Its two jobs are modest and specific. It builds the subprojects that make up Guacamole, and it provides a common central repository so that each of them resolves its siblings from one place. The README states each contained project is completely independent of guacamole-client and can be built separately, though others may need building first. Build everything through the superproject and Maven handles the ordering.

The top-level layout matches that description. guacamole/ is the web application itself, guacamole-common/ and guacamole-common-js/ are shared code for the server and browser sides, guacamole-ext/ holds protocol extensions, extensions/ holds the official extensions, guacamole-docker/ holds container build material, and src/ carries top-level sources. There is also a doc/ directory, a root pom.xml and a pom.xml per subproject, which is what makes the whole tree one reactor build.

The topics list includes both client and server roles, so do not expect this repository to be only a frontend.

## One command produces one deployable .war

The build is genuinely short, and the README does not pad it. From a checkout of the repository root:

```bash
mvn package
```

Maven downloads the dependencies needed for the.jar files, and once that completes the.war is created in the guacamole/target/ subdirectory of the current directory. That single command is the entire documented compile step for the whole application.

The output is a web application archive, not a daemon and not a package. Deployment is delegated to whatever servlet container you already run. Apache Tomcat, Jetty and other containers have specific and varying locations where a.war must be placed, and the README is explicit that these differ and that you will likely need to do the copy as root. No container-specific path, no service unit and no configuration file location is given in this repository, which is the first sign that operational knowledge lives in the manual rather than here.

The full manual is at http://guacamole.apache.org/doc/gug/ and pre-built.war files plus source archives are offered from the downloads section at http://guacamole.apache.org/. Compiling is an option for people who need a specific build, not the normal path to a running system.

## The container image encodes a real dependency you would otherwise miss

The Dockerfile at the repository root is more informative than the README about what a full build drags in. It declares two build arguments before anything else:

```dockerfile
ARG TOMCAT_VERSION=9
ARG TOMCAT_JRE=jdk21
```

Those exist so the image builder can choose an alternative runtime, and the file's own comment gives the example `--build-arg TOMCAT_JRE=jre8-alpine`. The default Tomcat 9 line on a JDK 21 base is the default combination, not a requirement.

The builder stage runs on the official maven image, maven:3-eclipse-temurin-21. Then the file does something that will break a naive reproduction: it installs software-properties-common, adds the Mozilla Firefox PPA, copies guacamole-docker/mozilla-firefox.pref into /etc/apt/preferences.d/, and installs firefox. The comment explains why. Newer Ubuntu has no firefox-esr package and ships only a transitional firefox package that actually pulls in Snap, which cannot be used inside a container. Firefox is installed for the sake of JavaScript unit tests.

That single dependency is the most useful thing in the file. If you clone the tree and run mvn package on a minimal machine, the browser-driven JavaScript tests are where you are most likely to stop.

## Where the protocol work lives

The extension split is how Guacamole keeps protocol support separable from the web application. guacamole-ext/ is the location for the extension modules, and extensions/ holds the official ones at the top level of the tree. The README does not enumerate which protocols are bundled by default, and it does not give a configuration recipe for adding one, so the supported protocol list has to be read out of the tree or out of the manual rather than from this documentation.

That matters for the evaluation question, because a remote desktop gateway is defined by what it can reach. A deployment that connects Windows hosts needs RDP, a Linux lab needs SSH or VNC, and the configuration key that binds those to a connection lives outside the build tree entirely. Building successfully tells you nothing about whether your target protocol is present.

The JavaScript side is equally separate: guacamole-common-js/ is the browser half of the shared code, and it is exercised by the unit tests that need a real browser, which is the loop back to the Firefox step in the container build.

## What this repository does not settle for you

Read the build documentation as strictly a build document and the gaps become clear.

There is no database instruction anywhere in the README. Guacamole stores connection configuration and history, and which database that lives in, how the schema is created, and how it is backed up are all questions this repository does not answer. The manual does.

Authentication is likewise outside the build. A gateway that carries keyboard, clipboard and file transfer to remote hosts needs a decision about who may connect, and that decision is not expressed in a pom.xml. 

One thing that does resolve cleanly is where problems go. Bug reports are filed in the Apache JIRA instance at https://issues.apache.org/jira/browse/GUACAMOLE/, not in GitHub issues. That is worth knowing before you spend an afternoon on a reproducible defect.

## Containerised deployment versus a packaged appliance

The alternative approaches split on who owns the runtime.

A packaged appliance wraps the .war together with a servlet container and a database into something a non-administrator can start. You get a working system with no build step and no Maven, at the cost of a component you did not choose and cannot easily inspect. For a homelab or a lab environment where nobody wants to run Tomcat, that trade is usually worth taking.

The superproject build inverts it. You get exactly the web application you asked for, on the container and runtime versions you name through the TOMCAT_VERSION and TOMCAT_JRE build arguments, with no extra daemon in the image. The cost is that you now own the servlet container's lifecycle, its upgrade path and its configuration, and you will need the manual rather than this repository to fill those in.

There is a third path worth naming: a public gateway service, where someone else runs the container and you only need the browser. That removes every operational question above and puts your session traffic on infrastructure you do not control.

## Licence and the cost of following main

Apache Guacamole is licensed Apache-2.0, with LICENSE and NOTICE at the repository root. For an organisation deploying it internally that means no copyleft obligation on your own configuration or on anything you write around it. For an organisation redistributing a modified build, the Apache 2.0 terms still require the NOTICE content and licence text to travel with the distribution, which is the practical difference from GPL code.

The repository is not archived and the last push was on 2026-10-14, so work is landing on the main branch at the time of writing. Note that this repository has no GitHub releases. Version numbers are not published through that channel, so the meaningful question at upgrade time is what the project website's downloads section and the manual say, not what the releases page says.

Upgrading a .war deployment is a replacement of the deployed file plus a restart, which is the simplest upgrade path in the category. It is also the moment where schema changes in your database can bite, and those changes are documented in the manual, not in this tree.

## Conclusion

Build guacamole-client when you need a browser-based remote desktop gateway and you already run a servlet container. Skip it if you want a packaged appliance, because the repository produces a.war and nothing else: the servlet container, the database schema and the authentication binding are decisions the deployer makes. First step for an evaluator is running mvn package at the repository root and confirming the artifact appears under guacamole/target/, since the whole project is defined by that one command producing one deployable file.

## FAQ

### How do I build Apache Guacamole from source?

Run mvn package from the repository root. Maven resolves the dependencies and writes the web application archive into the guacamole/target/ subdirectory, which you then copy to wherever your servlet container expects .war files.

### Which servlet container can deploy the guacamole-client .war file?

The README names Apache Tomcat and Jetty, and notes that different containers have specific and varying locations for .war files. The Dockerfile in the repository defaults to TOMCAT_VERSION=9 with TOMCAT_JRE=jdk21.

### Why does the Guacamole Docker build install Firefox from the Mozilla PPA?

The Dockerfile comment states that newer Ubuntu lacks a firefox-esr package and offers only a transitional firefox package that requires Snap, which cannot be used inside Docker. Firefox is installed so the JavaScript unit tests can run.

### Do I need guacamole-client if I just want to use Guacamole?

No. The README points to pre-built .war files and source archives on the project downloads page, and to the full manual at guacamole.apache.org/doc/gug/. Compiling is for technical users who need a specific build.

### Where do I report a bug in Guacamole?

The README directs bug reports to the Apache JIRA system at https://issues.apache.org/jira/browse/GUACAMOLE/ rather than to GitHub issues.

## Sources

- [apache/guacamole-client on GitHub](https://github.com/apache/guacamole-client)
- [Issues](https://github.com/apache/guacamole-client/issues)
- [License: Apache-2.0](https://github.com/apache/guacamole-client/blob/main/LICENSE)
- [Project website](https://guacamole.apache.org/)
- [README](https://github.com/apache/guacamole-client/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/apache-guacamole-client