Container & Build Infrastructure
Docker Compose setup for running Supermicro Java iKVM on ARM/macOS hosts: build approach, known errors, and SMB file sharing for IPMI virtual media.
The containerized Java iKVM setup runs the Supermicro/ATEN KVM console inside a Docker container with browser and VNC access, working around 32-bit Java and native library incompatibilities on Apple Silicon hosts. This page covers the Docker Compose build approach, architecture compatibility requirements, known runtime errors, and the local SMB file share used for IPMI virtual media.
Dockerized Java iKVM
The Supermicro/ATEN Java iKVM client (iKVM__V1.69.40.0x0.jar, main class tw.com.aten.ikvm.KVMMain) runs inside a container built on jlesage/baseimage-gui (Debian 11). The container exposes a browser-accessible VNC UI on port 5800 and a direct VNC port on 5900.
Build Approach
The build context lives under ./build. The compose service references the local build path rather than a pre-built registry image. A wrapper fix named ipmikvm-tls2020 is included. A persistent /config volume and a virtual media folder are both mounted into the container.
Key compose parameters:
| Parameter | Value |
|---|---|
| Build context | ./build |
| Web UI port | 5800 |
| VNC port | 5900 |
| Persistent config mount | /config |
Architecture Compatibility
ARM host requires x86/i386 emulation
Apple Silicon (ARM) hosts cannot run the 32-bit x86 Java native libraries that iKVM requires without emulation. The container image must include qemu-i386 and the 32-bit dynamic linker (ld-linux.so.2). Do not assume old iKVM native libraries work cleanly on Apple Silicon without explicit emulation support.
The ikvm64 native library and the i386/server libjvm.so must both be present inside the container image. Keeping architecture compatibility explicit at every build step avoids silent failures at runtime.
Known Errors
The following errors were encountered during the containerized iKVM build and are likely to recur:
| Error | Root cause |
|---|---|
qemu-i386 or ld-linux.so.2 missing | 32-bit emulation not installed in the container image |
| Headless exceptions | Display server not running or misconfigured |
connect failed with repeated retries | KVM data channel port unreachable (not a TLS or credential issue) |
no ikvm64 in java.library.path | Native library not copied to the expected path inside the container |
Missing i386/server libjvm.so | 32-bit JVM not installed in the image |
Ephemeral ports 63630/63631 refused or blocked | Host firewall, VPN, or NAT blocking the KVM data channel port |
Repeated retries and "connect failed" usually mean a blocked port
If the iKVM web UI loads but the session fails to connect or retries indefinitely, the KVM data channel port is blocked — not a certificate or credential issue. The ephemeral port is negotiated per session; trace which port iKVM is attempting and ensure the path from the container host to the IPMI address is open. See IPMI / KVM for diagnostics.
SMB Virtual Media / ISO Mount
Older Supermicro IPMI virtual media implementations require SMB 1.0. Modern macOS SMB rejects the authentication protocol these IPMI versions expect, so authentication failures against a macOS file share are typically a protocol version mismatch, not wrong credentials.
macOS SMB is incompatible with older Supermicro virtual media
If virtual media authentication fails despite correct credentials, the cause is SMB version incompatibility. Use a Windows VM, or a Linux/Docker Samba container configured with min protocol = NT1, to serve the ISO share. See IPMI / KVM for a minimal smb.conf example.
When SMB virtual media is unreliable, these alternatives apply:
- IPMIView on Windows — the most reliable virtual media path
- Physical USB drive with the Proxmox ISO written via
ddor Balena Etcher - Temporary PXE/netboot server on the same LAN
- A Linux/Docker Samba container with SMB 1.0 enabled on the same LAN
Related Pages
- IPMI / KVM — full runbook for IPMI access, Java iKVM troubleshooting, and the SMB
smb.confexample - Per-Site Inventory — host hardware models and IPMI addresses
- Build Phases — ordered sequence for bringing up each site
Kafka & Database Performance
Kafka blue/green cutover patterns, ordered consumer processing strategy, and PostgreSQL observability and transaction tuning guidance.
CA & Certificate Infrastructure
Certificate strategy for the AORXI homelab: Let's Encrypt DNS-01 via Cloudflare for OPNsense, Proxmox, PBS, and Kubernetes; step-ca private CA for IPMI/BMC and internal mTLS.