Run any Java Swing application inside a modern web browser — pure HTML5, zero plugins, zero client-side installation.
Getting Started · Build · Upgrading · What's New · Architecture
Suramadu renders Java Swing applications into an HTML5 Canvas and delivers them to any browser over a WebSocket. Your application runs unchanged on the server; the browser only draws the window.
The project is a fork of WebSwing v20.2.5, the last release published under the GNU AGPL v3. It is maintained by Manticore Projects to keep that codebase running on current JDKs, with a focus on modern JDK compatibility, security hardening and build toolchain modernization.
Suramadu is not affiliated with, endorsed by, or supported by Webswing Limited or Webswing s.r.o.
The Suramadu is the bridge that crosses from Java to the island of Madura — 5.4 km of cable-stayed span across the Madura Strait, first proposed in the 1960s and finally opened in 2009. It seemed a fitting name for software whose whole job is carrying Java across to somewhere else.
Suramadu is licensed under the GNU AGPL v3. If you interact with a running instance over a network, you are entitled to the complete corresponding source of that instance under section 13 of the licence.
The complete corresponding source for every released version is in this repository. Releases are tagged; deployed instances link back here.
Recommended standard OpenJDK distributions: Eclipse Temurin, BellSoft Liberica, or Amazon Corretto.
| JDK | Status | Temurin Support | Notes |
|---|---|---|---|
| 17 (LTS) | 🔶 Supported | Oct 2027 | Toolchain of the build |
| 21 (LTS) | ✅ Supported | Dec 2029 | |
| 23 | ✅ Supported | ⛔ EOL (Mar 2025) | Non-LTS, 6-month lifecycle |
| 25 (LTS) | ✅ Supported | Sep 2031 | Current LTS |
| 26 | ✅ Supported | Sep 2026 | Non-LTS; requires --sun-misc-unsafe-memory-access=allow |
All internal APIs adapted for the post-JDK-11 module system — no --illegal-access=permit, no -noverify required.
Beware: JetBrains Runtime modifies AWT's internal keyboard focus dispatch, which breaks when the toolkit is replaced. Mouse events are unaffected because they bypass the patched focus path.
Try the Online JSQLFormatter running on Suramadu 
- Truly headless operation on Linux — no X server, no Xvfb, no virtual framebuffer. AWT initialises against an
--patch-module–injectedGraphicsEnvironment+FontManagerFactorythat bypasslibawt_xawt.soentirely. A*-jre-headlessJDK package is sufficient; container images shrink accordingly. - Shiro Security Plugin with hot configuration reloading provides authorization via AD/LDAP/Database/Text Files with or without 2FA (Second Factor authorization)
- SVG Application Icons
- better server start scripts supporting SSL certificate registration and WAR version numbers
- Deduplication of the java libraries in the WAR file, reducing the size drastically
- Network resilience for flaky corporate VPNs (Netskope, Zscaler) — HTTP/2 via ALPN, Conscrypt TLS (tolerates underscored SNI hostnames), per-socket TCP keepalive, 5-minute idle timeouts, TLS session resumption, tuned thread pool with
LowResourceMonitor
- Node.js 24 LTS — migrated from Node 10; Webpack 5, TypeScript 5, Dart Sass
- Gradle build system — fast, incremental builds
- All dependencies updated — Jetty 12, Jackson 3, Guava, Log4j2, SLF4J 2.0, Apache Commons, Protocol Buffers, LZ4, and more
- SSE/AVX-optimized PNG encoding via zpng-java — hardware-accelerated image compression in the DirectDraw rendering pipeline
- Browser-side font rendering — text is rendered as font names + coordinates instead of server-side glyph bitmaps, reducing WebSocket bandwidth by up to 80%
- GZIP/Brotli pre-compression for all static assets (reducing the JS size from 5 MB to less than 1 MB), GZIP compression for all content (JSON)
The fork is hardened for the deployments it was built for.
Continuous monitoring via Snyk (dependency CVEs), Semgrep (SAST/OWASP Top 10), SpotBugs (bytecode analysis), and Codacy (code quality). CycloneDX SBOM generated with every release.
Proactive hardening against entire vulnerability classes — not just known CVEs: deserialization allowlists (CWE-502), SSRF scheme validation (CWE-918), XSS content-type enforcement (CWE-79), Zip Slip / path traversal protection (CWE-22), log injection sanitisation (CWE-117), AES-CBC→AES-GCM migration, and HMAC-signed file identifiers.
Runtime — non-root Docker container on Eclipse Temurin JRE 21 (Ubuntu Noble), multi-stage build excluding source and build tools from the image.
Supply chain — CycloneDX SBOM output supports transparency requirements under NIST SP 800-218 and the EU Cyber Resilience Act.
| Component | Version |
|---|---|
| JDK | 17 or later (21+ recommended; Eclipse Temurin). A headless JDK distribution is sufficient on Linux servers — see below. |
No X server, no Xvfb, no virtual framebuffer required. Suramadu 26.4.7 runs truly headless on Linux via --patch-module java.desktop replacements for GraphicsEnvironment, PlatformGraphicsInfo, and FontManagerFactory. The standard *-jre-headless package from your distribution (or any JRE/JDK without the GUI dependencies) is enough. DISPLAY is explicitly unset by the startup script; nothing in the child Swing JVM ever calls into libawt_xawt.so or attempts a display connection.
# Download the latest release
curl -LO https://github.com/manticore-projects/suramadu/releases/latest/download/suramadu-26.4.7.zip
unzip suramadu-26.4.7.zip
cd suramadu-26.4.7
# Start the server
./run.sh start
# Open in your browser
open http://localhost:8080./run.sh start # Start the server (background, with log tailing)
./run.sh stop # Graceful shutdown (30s timeout, then SIGKILL)
./run.sh restart # Stop + Start
./run.sh status # Check if the server is running| Tool | Version |
|---|---|
| JDK | 21+ |
| Gradle | 8.12 |
| Git | 2.x |
Node.js and npm are automatically downloaded during the build — no manual installation needed.
# Clone the repository
git clone https://github.com/manticore-projects/suramadu.git
cd suramadu
# Full build
./gradlew clean build
# Build specific modules
./gradlew :suramadu-directdraw:suramadu-directdraw-javascript:build
./gradlew :suramadu-server:suramadu-server-frontend:build# Extract to your deployment directory
unzip build/dist/suramadu-26.4.7.zip -d /opt/suramadu
# Configure your Swing application
vim /opt/suramadu/suramadu.config
# Start
cd /opt/suramadu && ./run.sh startEverything a user or administrator touches now carries the suramadu name. Everything that would
break a running deployment — system properties, Java packages, the public API — is unchanged.
| Before | Now | |
|---|---|---|
| Distribution archive | webswing-<version>.zip |
suramadu-<version>.zip |
| Web application | webswing-server-<version>.war |
suramadu-server-<version>.war |
| Application configuration | webswing.config |
suramadu.config |
| Server properties | webswing.properties |
suramadu.properties |
| Gradle modules and jars | webswing-* |
suramadu-* |
| Docker image | — | manticore-projects/suramadu |
| System properties | -Dwebswing.* |
unchanged |
| Jetty properties keys | org.webswing.server.* |
unchanged |
| Java packages and API | org.webswing.* |
unchanged |
No action is required to upgrade. Existing webswing.config and webswing.properties files are
still read, so an installation created before the rename keeps working untouched. Rename them when
convenient, or leave them. Where both names are present, the suramadu.* files take precedence.
Java packages keep the org.webswing namespace deliberately: renaming them would break every
deployment that references a class by name, and would require altering the copyright and licence
notices the AGPL obliges us to preserve. They are internal identifiers, not product names.
How it works: The server intercepts Java2D Graphics2D paint operations in the child JVM, serializes them via Protocol Buffers, and streams them over WebSocket to the browser. The browser's JavaScript engine deserializes and replays the draw commands on an HTML5 Canvas. User input (mouse, keyboard) flows back over the same WebSocket.
| Component | Version | Purpose |
|---|---|---|
| Jetty | 12.1.+ | Embedded HTTP/WebSocket server |
| Jackson | 3.+ | JSON serialization |
| Protocol Buffers | 3.+ | Binary wire format (DirectDraw) |
| Apache Shiro | 3.+ | Authentication & authorization |
| Guava | 33.+ | Core utilities |
| Log4j 2 | 2.+ | Logging framework |
| SLF4J | 2.+ | Logging facade |
| Webpack | 5.+ | JavaScript bundling |
| TypeScript | 5.+ | Type-safe frontend code |
Suramadu is derived from WebSwing v20.2.5, the last release published under the GNU AGPL v3. All credit for the original architecture and implementation belongs to its authors.
Suramadu is not affiliated with, endorsed by, or supported by Webswing Limited or Webswing s.r.o.
This project is licensed under the GNU Affero General Public License v3.0.
Maintained by Manticore Projects
Building enterprise financial software for banks and insurances since 2011.