# Supermicro Java iKVM in Docker: A Browser-Based Workaround with Known Rough Edges > MisterCalvin/supermicro-java-ikvm packages a Java-based Supermicro iKVM viewer into a Docker container with a web UI and VNC access. It works around browser Java plugin removal, but the README lists real bugs and a narrow hardware test range. **MisterCalvin/supermicro-java-ikvm** — A container for connecting to Supermicro Java based iKVM viewers via a web browser - Repository: https://github.com/MisterCalvin/supermicro-java-ikvm - Stars: 102 · Forks: 25 - Language: Shell - License: MIT - Published: 2026-08-17 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/mistercalvin-supermicro-java-ikvm ## The Problem: Java iKVM Without a Browser Plugin Supermicro's older BMCs rely on a Java Web Start application for remote KVM. Modern browsers dropped Java plugins, so administrators lose console access unless they keep a legacy browser or use a standalone Java runtime. This project solves that by wrapping the iKVM viewer in a Docker container based on jlesage/docker-baseimage-gui. That base image provides a noVNC web interface and a VNC server, so the Java application runs inside the container and you interact with it through a browser on port 5800 or a VNC client on port 5900. The intended user is an IT administrator who manages Supermicro servers with Java-based iKVM and wants a reproducible, containerized way to reach them. The README does not claim support for all Supermicro models; it specifically mentions testing on an X9DR3-F motherboard with a Nuvoton WPCM450 BMC and firmware 3.62. That is a narrow claim, and you should read it as a warning that other firmware revisions may behave differently. ## How It Works: Base Image and Initialization Script The container builds on jlesage/docker-baseimage-gui, which handles the GUI environment, VNC server, and web interface. The project adds an initialization script at `build/rootfs/etc/cont-init.d/50-setup-ikvm.sh`. According to the README, this script fetches the iKVM .jar file from the target server. The script hardcodes a URL as `url="https://$KVM_HOST"` on line 28. That means the container assumes the server's web interface is reachable over HTTPS on the default port 443. The script likely downloads the Java application and then launches it inside the virtual display. User preferences and the downloaded .jar files persist in a named volume mounted at `/config/`. The README notes that not all preferences are saved; hotkeys, mouse settings, and keyboard settings persist, but Virtual Media mounts and Video Settings do not. This is a critical limitation because remounting an ISO after every container restart is tedious. The data flow is: browser to noVNC, noVNC to VNC, VNC to the Java iKVM application, which talks to the BMC over HTTPS. Each layer adds complexity, and the README's bug list shows where that complexity leaks. ## Getting It Running: Compose and CLI The README provides two deployment methods. For Docker Compose, you define a service with the image `ghcr.io/mistercalvin/supermicro-java-ikvm:latest`, set environment variables for `KVM_HOST`, `KVM_USER`, `KVM_PASS`, `DISPLAY_WIDTH`, and `DISPLAY_HEIGHT`, and publish ports 5800 and 5900. You also mount volumes for Virtual Media ISO files at `/app/vmedia/` and screenshots at `/app/screenshots/`. For the Docker CLI, you must first create a named volume with `docker volume create supermicro-java-ikvm`, then run the `docker run` command with the same environment variables and port mappings. The README stresses that the named volume persists user preferences and iKVM .jar files. Without it, you lose those on container recreation. The `USER_ID` and `GROUP_ID` environment variables let you set the UID and GID for the `app` user inside the container, which matters for file permissions on mounted volumes. The web UI is accessible at port 5800, and the README points to the base image's documentation for adding a VNC password. There is no mention of a healthcheck or a startup script beyond the initialization step. ## Known Bugs: Language Crash and Preference Loss The README is refreshingly honest about current bugs. The most severe is that selecting Español or Korean from Options > Preference > Language Setting causes a crash, and any attempt to reconnect to the Java viewer fails afterward. The workaround is to log into the server's web interface and navigate to Maintenance > iKVM Reset, or reboot the IPMI unit via Maintenance > Unit Reset. That is a heavy operation for a language setting. Another bug is that the UI may have issues on boot; the README suggests unchecking "Auto-resize window" in Options > Preference > Window. This is a workaround, not a fix, and it implies the viewer's window management is fragile. Preference persistence is partial, as noted earlier. These bugs are not edge cases; they are documented in the project's own README, so you should expect them. The language crash is particularly concerning because it can render the iKVM viewer unusable until a BMC reset, which could disrupt other IPMI functions. ## Limitations and Wrong-Tool Cases The container assumes your server's web interface is on port 80 or 443. If you use a non-standard port, the README says you may need to modify the initialization script at `build/rootfs/etc/cont-init.d/50-setup-ikvm.sh`, specifically line 28 where `url="https://$KVM_HOST"`. That is a hardcoded HTTPS assumption; there is no environment variable for the port. This is a significant limitation for environments that run IPMI on custom ports for security. Also, the container has only been tested with one specific motherboard and firmware revision. The README does not claim compatibility with other Supermicro models, so you cannot assume it works on an X11 or H12 board. The partial preference saving means Virtual Media mounts are lost on restart, which is a dealbreaker for anyone who regularly mounts installation ISOs. If you need persistent mounts or non-standard ports, this container is the wrong tool. A direct Java Web Start client or a dedicated IPMI tool might be more reliable, though they bring their own Java version headaches. ## Alternatives: What Else Is Out There The README credits Walter Doekes for the `ipmikvm-tls2020` script, which is a standalone script for Supermicro Java console redirection. That script is a direct alternative: it runs outside Docker, likely requires a Java runtime on the host, and does not provide a web UI. The Docker container here builds on that idea but adds the GUI base image, so you get browser access. Another alternative is to use a newer Supermicro BMC that supports HTML5 iKVM, which eliminates Java entirely. That is a hardware upgrade, not a software fix, but it is the cleanest long-term solution. The difference in approach: this container virtualizes the Java environment, while the ipmikvm script runs Java natively, and HTML5 iKVM removes Java altogether. If you have a mix of old and new Supermicro boards, you might need both this container and the HTML5 interface. The README does not compare these options, but the existence of the ipmikvm script shows that a non-Docker path exists. ## Maintenance and Upgrade Cost The project is not archived and is under the MIT license, which means you can modify it freely. However, the README notes that the image has additional environment variables from the base image that the author has not tested; using them is at your own risk. That is a maintenance concern because you cannot rely on the author's validation for those options. The initialization script is the piece most likely to need changes, especially for non-standard ports or different BMC firmware. Upgrading the container means pulling a new image, but the README does not describe a migration path for the `/config/` volume. The named volume persists .jar files and preferences, but if the image changes its internal paths, you might need to clear it. The license is MIT, so you can fork and fix bugs yourself, but the documented bugs (language crash, preference loss) have not been fixed as of the README's writing, so you should assume maintenance is on you. There is no release history or changelog in the provided material, so you cannot gauge how actively the project is updated. ## Conclusion Adopt this container if you manage a Supermicro server with a Java-based iKVM (the README confirms only an X9DR3-F with BMC firmware 3.62) and you need browser-based remote KVM without installing a Java plugin. Do not adopt it if your BMC uses a non-standard web port, if you rely on persistent Virtual Media mounts, or if you cannot tolerate a crash when switching to Español or Korean in the viewer preferences. Before production use, verify your exact motherboard and BMC firmware against the tested combination, test the language-switch crash on a lab unit, and confirm that the initialization script's hardcoded `url="https://$KVM_HOST"` works with your network setup. The container's value is real but narrow; it is a workaround, not a polished product. ## FAQ ### What is IPMI used for in this container? It is the management interface the container logs into. KVM_USER and KVM_PASS are your IPMI username and password, and KVM_HOST is the board's address, so the container authenticates to the baseboard management controller and drives the Java-based iKVM viewer it hosts rather than to the operating system of the managed server. ### How do I access the IPMI interface through this container? Start the container and open the web interface on the default port 5800, with port 5900 published as well for a native VNC client. The page is unprotected until you set a password, and the steps for that are in the upstream base image documentation the README links to. ### How do I configure IPMI? The container configures its own side through KVM_HOST, KVM_USER and KVM_PASS, and its display through DISPLAY_WIDTH and DISPLAY_HEIGHT. Board-side configuration is not documented here. The two server-side actions that are documented are resetting iKVM and rebooting the unit, both under Maintenance in the server's own web interface. ### How do I disable IPMI on a Supermicro device? This repository does not cover that. It only reaches a running IPMI interface through the Java iKVM viewer and describes recovering from a crashed viewer; it documents no procedure for switching IPMI off, and doing so would remove the very access path the container depends on. ## Sources - [Official README](https://github.com/MisterCalvin/supermicro-java-ikvm#readme) - [Project repository](https://github.com/MisterCalvin/supermicro-java-ikvm) - [README](https://github.com/MisterCalvin/supermicro-java-ikvm/blob/main/README.md) - [Releases](https://github.com/MisterCalvin/supermicro-java-ikvm/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/mistercalvin-supermicro-java-ikvm