CupCarbon in Docker (portable, GUI via browser)

This packages CupCarbon (classic V5, Java 8 / JavaFX) into a container. The GUI is exposed through noVNC, so you interact with it in a normal browser tab — this works the same way on Linux, macOS, and Windows hosts, with no X11 forwarding setup needed.

Prerequisites on your machine

• Docker + Docker Compose installed (Docker Desktop on Mac/Windows, Docker Engine + compose plugin on Linux).
• A web browser.
• ~1 GB free disk for the image.

Step 1 — Get the CupCarbon zip (manual, one-time)

cupcarbon.com blocks automated downloads (bot detection), so this one step can't be scripted. Do it once, by hand:

1. Go to http://cupcarbon.com/download_klines.php in your browser (this is the real application download — do not use GitHub's "Download ZIP" button, which only gives raw source code with no compiled jar).
2. Download the Linux x64 package.
3. Rename the downloaded file to cupcarbon.zip.
4. Place it here in this project:

   cupcarbon-docker/
   ├── Dockerfile
   ├── docker-compose.yml
   ├── supervisord.conf
   ├── start-cupcarbon.sh
   ├── README.md
   └── cupcarbon-src/
       └── cupcarbon.zip      <-- put it here
   

The unzipped package should contain cupcarbon.jar directly alongside a linuxx/ folder (which itself contains lib/, the bundled JavaFX modules) — start-cupcarbon.sh looks for exactly this layout.

If your CNAM/ISEP account gives you access to a specific version (they mention providing CupCarbon access in your thesis proposal), use that exact zip instead — version consistency with what your advisor/reviewers expect matters more than always grabbing the newest release.

Step 2 — Build and run

cd cupcarbon-docker
docker compose up --build

First build takes a few minutes (installing Xvfb, noVNC, etc.). Once you see log lines from cupcarbon, x11vnc, and novnc in the terminal, it's ready.

Step 3 — Open the GUI

Open in your browser:

http://localhost:6080/vnc.html

Click Connect (no password by default — see "Adding a VNC password" below if you want one). You should see a plain desktop (fluxbox) with the CupCarbon window already open.

Step 4 — Save your work

Anything you save from inside CupCarbon to /opt/cupcarbon/projects/ (use that as your default save location in the app) will appear on your host machine under cupcarbon-docker/projects/ — it persists across container restarts and rebuilds. Save your .cup project files there, not elsewhere in the container filesystem, or you'll lose them on the next rebuild.

Stopping / restarting

docker compose down        # stop and remove the container (projects/ is untouched)
docker compose up          # start it again (no rebuild needed unless the Dockerfile changed)

Troubleshooting

• Blank/black screen in the browser — refresh the tab; occasionally the noVNC proxy connects before Xvfb finishes initializing. If it persists, check logs: docker compose logs cupcarbon.
• "could not find cupcarbon.jar" in logs* — the zip layout wasn't what start-cupcarbon.sh expected. Run docker compose exec cupcarbon find /opt/cupcarbon -maxdepth 3 to see the actual layout, then adjust the find pattern in start-cupcarbon.sh accordingly (tell me what it prints and I'll fix the script for you).
• JavaFX / module resolution errors on startup — double check you downloaded from download_klines.php and picked the Linux x64 package specifically. If the zip's internal folder is named something other than linuxx (e.g. a version-specific name), start-cupcarbon.sh still finds it (it searches for any lib/ folder near the jar), but if it still fails, run docker compose exec cupcarbon find /opt/cupcarbon -maxdepth 3 and paste me the output.
• Performance feels sluggish over noVNC — normal for GUI-over-browser; it's fine for design/configuration work. If you need it snappier for long sessions, a native VNC client (e.g., TigerVNC, RealVNC) connecting to localhost:5900 is noticeably faster than the browser canvas.

Adding a VNC password (optional, recommended if the ports are ever exposed beyond localhost)

Edit supervisord.conf, change the x11vnc line from -nopw to -rfbauth /root/.vnc/passwd, and add a step in the Dockerfile to generate that file with x11vnc -storepasswd <password> /root/.vnc/passwd at build time (or better, mount it as a secret rather than baking it into the image).

Why this design (vs. X11 forwarding)

X11 forwarding (-v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY=$DISPLAY) is simpler on native Linux but breaks portability — it needs XQuartz + extra config on macOS and is fragile on Windows/WSL2. Since you explicitly want "everything in containers to ensure portability," noVNC trades a small amount of GUI responsiveness for identical behavior on any host OS, and it's also the only approach that works cleanly if you ever move this to a remote server (e.g., run the simulations on a lab machine and just leave the browser tab open from your laptop).