r/javascript • • 3d ago

A server-rendered Node.js app that drives Docker: what I learned building a Minecraft server panel in plain JS (express, dockerode, ws, node:sqlite)

https://github.com/anefzaoui/minecraft-server-manager

Source (MIT): https://github.com/anefzaoui/minecraft-server-manager

It's a web panel that runs Minecraft servers as Docker containers, built for the modpack servers I run for friends and family. Disclosure up front: I built it with Claude Code. I designed it, decided every feature, review the changes and test every release on our own servers, and Claude wrote most of the code. The JS choices below are the parts I think are worth talking about:

  • Plain JS, type-checked. No build step for the server: it's JavaScript with JSDoc types, and tsc --checkJs runs over the core in CI. Typos in property names get caught, and stack traces point at the file you actually wrote
  • One direction of layering. routes (parse + zod-validate, no logic) → services (the features) → docker / db / storage. A route never touches dockerode or the database directly, which made it easy to test services without Docker
  • node:sqlite instead of a driver. Node 24's built-in SQLite, synchronous, WAL, with one module that owns it and a prepared-statement cache keyed on the SQL text. No native module to compile on arm64
  • dockerode, never the docker CLI. Containers, logs, stats and image pulls all go through the Docker API, and a watcher turns Docker events into history and crash detection
  • Brokered WebSockets. The live console opens one upstream docker logs --follow per server and fans it out to every open tab, instead of one stream per tab. Upgrades check Origin and the session cookie
  • Server-rendered. express + Handlebars, with a small esbuild bundle for the interactive bits and CSP nonces on every response (no unsafe-inline scripts)
  • A path guard on every file operation. Everything lives under one data folder, and every path is checked against escaping it, symlinks included

Tests run on node:test with no Docker needed, plus a live QA sweep script that hits a running panel.

Happy to go deeper on any of these, and I'd love to hear if someone has a nicer pattern for brokering log streams.

0 Upvotes

6 comments sorted by

1

u/gianluca_caruso-6 1d ago

Do slow tabs get bounded queues, so one backed-up WebSocket can't delay log delivery to every subscriber?

1

u/Nefzaoui 1d ago

good question! one slow tab can't hold up the others. there's one docker logs stream per server and each chunk is ws.send()'d to every tab in a plain loop, nothing awaited, so a slow socket just piles up in its own buffer while the rest keep getting lines. the shared stream never pauses for anyone.

it's not a true bounded queue though, nothing gets dropped or merged. after every chunk it checks each socket's bufferedAmount, and a tab that stays above 4 MB for over 5 s gets a "fell behind, reload" message and is closed. reloading catches it up from the last 256 KB. code's here if you want to poke at it https://github.com/anefzaoui/minecraft-server-manager/blob/main/src/ws/index.js#L167-L194

0

u/fracturetrey 2d ago

I've been using this for a few weeks now and it's been perfect for me. I was new to MC server administration altogether so there was a bit of a learning curve, but in the end I found the panel helped me make sense of the game's data model. Thanks for putting the project together!

0

u/Nefzaoui 2d ago

this made my day, thank you so much 🙏 and that's exactly the kind of thing i hoped for, that the panel makes the game's moving parts easier to follow instead of hiding them. if anything ever confuses you or breaks, open an issue on GitHub and i'll look at it.