|
| 1 | +# jnlp-anywhere |
| 2 | + |
| 3 | +Java Web Start was a raging dumpster fire — arbitrary code execution from a URL, signed with certificates that could be compromised, running with permissions the user probably didn't intend to grant. |
| 4 | + |
| 5 | +Since it was officially killed in Java 11, and banished from the browsers long before that, it is no small task to access these applications with modern software. |
| 6 | + |
| 7 | +jnlp-anywhere is a container that solves the access problem without solving it on your workstation. It fetches the JNLP file from the target device at runtime, parses it, downloads whatever jars the application needs, and runs it inside an Xpra session accessible from any browser. No Java on your machine. No plugin. No Web Start. Just a URL. |
| 8 | + |
| 9 | +Running these applications carries inherent risk that exists regardless of how you access them. jnlp-anywhere contains the execution environment but does not sanitize or inspect the application being run. The security posture of the application itself is your problem, not this container's. |
| 10 | + |
| 11 | +--- |
| 12 | + |
| 13 | +## Project Status |
| 14 | + |
| 15 | +This has only been tested on x86_64 via the Quick start command line with an ISY-994 as target. |
| 16 | + |
| 17 | +Container is not optimized or hardened; There are no protections against naughty webstart applications. |
| 18 | + |
| 19 | +**No lifeguards are present. Swim at your own risk.** |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## How it works |
| 24 | + |
| 25 | +Point it at a JNLP URL. Everything else is derived automatically. Hopefully. |
| 26 | + |
| 27 | +``` |
| 28 | +JNLP_URL=http://192.168.1.x/admin.jnlp |
| 29 | +``` |
| 30 | + |
| 31 | +The container fetches the JNLP file, parses the codebase, downloads all declared jars, constructs the classpath, extracts the main class and any application arguments, and launches the application under Xpra. The HTML5 client is served on the same port. Open a browser, get a window. |
| 32 | + |
| 33 | +The native Xpra client also works on the same port. However, inclusion is incidental. |
| 34 | + |
| 35 | +--- |
| 36 | + |
| 37 | +## Requirements |
| 38 | + |
| 39 | +- A container platform - Docker, Kubernetes, Podman, whatever (maybe) |
| 40 | +- A device serving a JNLP file on a reachable URL with no authentication |
| 41 | +- Java 8 compatible application (most legacy JNLP applications are) |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## Quick start |
| 46 | + |
| 47 | +```bash |
| 48 | +docker run -e JNLP_URL=http://192.168.1.x/admin.jnlp \ |
| 49 | + -p 14500:14500 \ |
| 50 | + ghcr.io/lostsynapse/jnlp-anywhere:latest |
| 51 | +``` |
| 52 | + |
| 53 | +Open `http://localhost:14500` in a browser. |
| 54 | + |
| 55 | +--- |
| 56 | + |
| 57 | +## Authentication |
| 58 | + |
| 59 | +jnlp-anywhere supports four authentication modes ranging from no authentication to layered proxy and application-level auth. The right choice depends on your network topology and threat model — that decision is yours to make. |
| 60 | + |
| 61 | +See the [Traefik + Authentik integration guide](docs/traefik-authentik.md) for one complete deployment pattern. Orchestration examples for Swarm and k3s are in the [examples](examples/) directory. |
| 62 | + |
| 63 | +--- |
| 64 | + |
| 65 | +## Environment Variables |
| 66 | + |
| 67 | +| Variable | Required | Description | |
| 68 | +| --- | --- | --- | |
| 69 | +| `JNLP_URL` | Yes | Full URL to the JNLP file | |
| 70 | +| `XPRA_PASSWORD` | No | Enables password authentication on the Xpra session. If unset, the session is unauthenticated. | |
| 71 | +| `XPRA_PRESEED_PASSWORD` | No | Set to `true` to write the password into the HTML5 client's default settings, pre-filling the connect dialog. Requires `XPRA_PASSWORD`. Do not use if the port is directly exposed without a reverse proxy — the password will be served to any browser that can reach it. | |
| 72 | +| `XPRA_AUDIO` | No | Set to `true` to enable audio forwarding via PulseAudio. Disabled by default. May be supported by JNLP applications that use audio output such as IPMI SOL viewers. (untested) | |
| 73 | +| `XPRA_DEBUG` | No | Set to `1` for Xpra verbose logging. Set to `2` for shell trace. Set to `3` for both. | |
| 74 | + |
| 75 | +--- |
| 76 | + |
| 77 | +## Session lifecycle |
| 78 | + |
| 79 | +Understanding how the container behaves across different exit scenarios is important for choosing the right deployment model. |
| 80 | + |
| 81 | +**Application exits normally** — the user closes the application window. The Xpra session ends, the container exits, and the orchestrator restarts it per the configured restart policy. The next connection fetches a fresh JNLP and starts clean. This is the expected cluster behavior. |
| 82 | + |
| 83 | +**Application crashes** — same path as a normal exit. If the crash is reproducible the orchestrator will restart with backoff and eventually mark the service as failed. Worth monitoring if the target application is known to be unstable. |
| 84 | + |
| 85 | +**Browser disconnects** — Xpra keeps the application session alive when the browser disconnects. The Java application continues running inside the container. Reconnecting from any browser resumes the existing session. The container does not exit on browser disconnect. |
| 86 | + |
| 87 | +**Container running with no active connection** — the application runs idle until the user reconnects, the application itself times out, or the service is manually disabled. For occasional management tasks this is acceptable. For resource-constrained clusters it is worth considering. |
| 88 | + |
| 89 | +**Recommended cluster behavior** — deploy with a restart policy so the container recovers from application exits and crashes automatically. Disable the service manually when the management task is complete rather than relying on automatic teardown. This gives full control over when the resource is consumed without requiring intervention for transient failures. |
| 90 | + |
| 91 | +**Quick access without an orchestrator** — the `docker run` one-liner in the quick start section is the right tool for a single session. The container exits when the application closes and does not restart. No cleanup required. |
| 92 | + |
| 93 | +--- |
| 94 | + |
| 95 | +## Known limitations |
| 96 | + |
| 97 | +**Java version:** The container runs OpenJDK 8. Applications requiring a newer or older Java version are not supported. |
| 98 | + |
| 99 | +**Multi-jar applications:** All jars declared in the JNLP resources block are downloaded and added to the classpath. Applications that dynamically load additional jars at runtime outside the JNLP declaration may not work correctly. |
| 100 | + |
| 101 | +**Signed jars and security dialogs:** Some applications present security dialogs during launch. These will appear in the Xpra session and must be accepted manually on first run. |
| 102 | + |
| 103 | +**Session persistence:** The container runs a single Xpra session tied to the application lifecycle. When the application exits, the container exits. This is intentional — the container is not designed as a persistent desktop. |
| 104 | + |
| 105 | +**Native client through a proxy:** The native Xpra client cannot complete an OIDC authentication flow. It connects directly to port 14500 only. See the auth documentation for details. |
| 106 | + |
| 107 | +**App windows misbehave:** Some independent windows that should be hidden at start are not, may be layered incorrectly or differently than you expect, program is ugly, etc. |
| 108 | + |
| 109 | + |
| 110 | +--- |
| 111 | + |
| 112 | +## License |
| 113 | + |
| 114 | +MIT. Do what you want with it. |
0 commit comments