August 22, 2025
I rewrote the whole thing in Go over a weekend
The JavaScript backend worked. It also couldn't ship as one binary. I threw it away and rebuilt it in Go, a language I had never used, over three days.
Why

The JavaScript version worked. I want to be clear about that. It deployed containers, it showed a dashboard, it managed Docker. It was real software. It was also held together with spawn() calls, CORS workarounds, and hand-patched YAML, and every new feature cost me more time fighting the runtime than building the thing I actually wanted.
The part that decided it was distribution. I wanted HomelabARR to be one file. Download it, chmod +x, run it, done. Node does not do that cleanly. You ship a runtime, a node_modules tree, and a build step, or you ship nothing. Go compiles to a single static binary, and that one fact was the whole reason for the rewrite.
I had never written a line of Go. I didn't know the syntax or the standard library. What I did have was a working JavaScript implementation to read as a spec, and the one thing a PM brings to a rewrite: I knew exactly what the system had to do. I just needed a language that would let it ship as one file.
The before: spawn() and CORS
This is the thing I was rewriting. The JavaScript backend drove Docker by shelling out to the CLI as a child process. server/cli-bridge.js opened with the tell:
// homelabarr-legacy/server/cli-bridge.js
import { execSync, spawn } from 'child_process';
// ...
const dockerCompose = spawn('docker-compose', ['-f', appPath, ...command.split(' ')], { /* ... */ });
// ...
const installer = spawn('bash', [path.join(this.traefik, 'install.sh')], { /* ... */ });
Every deploy was a spawned process. Container state came from running docker ps and parsing its stdout. The HTTP layer was Express, with a CORS config that had grown its own helper class:
// homelabarr-legacy/server/index.js
import express from 'express';
import cors from 'cors';
// ...
app.use(cors(EnvironmentManager.getCorsOptions()));
app.use(helmet({ /* ... */ }));
It worked. It also could never become one binary, because none of it could.
The weekend, in one commit
An earlier draft of this post hedged that I couldn't git show the three-day diff. That was wrong, and I should have looked harder before saying it. The rewrite is right there in the homelabarr-cli history, landed in a single commit on the morning of August 21, 2025:
commit 1676054d Thu Aug 21 04:23:29 2025 -0400
feat: Implement HomelabARR v2.0 architecture with Go CLI and Web GUI
14 files changed, 941 insertions(+), 0 deletions(-)
v2-poc/cmd/homelabarr/main.go | 20 ++
v2-poc/cmd/homelabarr/commands/{root,server,deploy}.go
v2-poc/internal/api/server.go | 119 ++
v2-poc/go.mod | 13 ++
v2-poc/web/src/App.tsx | 53 ++
v2-poc/Dockerfile, .goreleaser.yml, modules/traefik/*.tf, ...
A whole v2-poc/ tree in one shot: a Cobra command tree, a Gorilla Mux API server, an embedded React app, a Dockerfile, and the GoReleaser config for the single-binary build. The spawn-the-CLI backend became this:
// v2-poc/internal/api/server.go (Aug 21, 2025)
type Server struct {
Router *mux.Router
dockerClient *docker.Client
stackManager *stack.Manager
}
func (s *Server) setupRoutes() {
api := s.Router.PathPrefix("/api/v1").Subrouter()
api.HandleFunc("/health", s.handleHealth).Methods("GET")
api.HandleFunc("/stacks", s.handleListStacks).Methods("GET")
api.HandleFunc("/stacks/{name}/deploy", s.handleDeployStack).Methods("POST")
api.HandleFunc("/stacks/{name}/destroy", s.handleDestroyStack).Methods("DELETE")
// ...
}
A Docker API client took over where there had been a spawned docker-compose, and a Gorilla router replaced Express.
What the module path remembers
The go.mod is the part that doesn't lie about lineage. It was born small that weekend:
module github.com/smashingtags/homelabarr-cli/v2
go 1.21
require (
github.com/spf13/cobra v1.8.0
github.com/spf13/viper v1.18.2
github.com/docker/docker v24.0.7+incompatible
github.com/hashicorp/terraform-exec v0.19.0
github.com/sirupsen/logrus v1.9.3
github.com/fatih/color v1.16.0
)
A v2 proof of concept forked off the CLI repo, with the Docker SDK as a real dependency instead of me parsing docker stdout. By the time the repo was archived, the same module had grown into what the rewrite was always going to need:
module github.com/smashingtags/homelabarr-cli/v2-poc
go 1.23.0
require (
github.com/docker/docker v28.3.3+incompatible
github.com/gorilla/mux v1.8.1
github.com/gorilla/websocket v1.5.3
github.com/syndtr/goleveldb v1.0.0
github.com/rs/cors v1.11.1
github.com/spf13/cobra v1.8.0
...
)
Gorilla WebSocket for live updates, LevelDB (goleveldb) for state, and rs/cors doing properly what the Express middleware had done by hand.
State persistence went through LevelDB, opened once at startup. This is the actual store code, no spawning, no YAML on disk:
// pkg/state/db.go
type Database struct {
db *leveldb.DB
path string
}
func NewDatabase(dataDir string) (*Database, error) {
if err := os.MkdirAll(dataDir, 0755); err != nil {
return nil, fmt.Errorf("failed to create data directory: %w", err)
}
dbPath := filepath.Join(dataDir, "state.db")
db, err := leveldb.OpenFile(dbPath, &opt.Options{
ErrorIfMissing: false,
WriteBuffer: 4 * opt.MiB,
})
if err != nil {
return nil, fmt.Errorf("failed to open database: %w", err)
}
return &Database{db: db, path: dbPath}, nil
}
func (d *Database) SaveStack(stack *StackState) error {
key := fmt.Sprintf("stack:%s", stack.Name)
data, err := json.Marshal(stack)
// ...
}
The one-file claim, made real
The distribution argument only holds if the frontend ships inside the binary too. Go's embed package is how that works, and it is in the tree:
// internal/webui/embed.go
//go:embed all:dist
var webUI embed.FS
func GetFileSystem() http.FileSystem {
fsys, err := fs.Sub(webUI, "dist")
if err != nil {
panic(err)
}
return http.FS(fsys)
}
The built React dashboard gets compiled straight into the executable. The Compose templates were embedded the same way. So the binary really is the API server, the frontend, and the templates in one file. That was the thing Node could not give me, and it is the whole reason any of this happened.
The architecture I could only build the second time

The layout was right from the start because I already knew the shape. cmd/homelabarr/ for the CLI and server entry, with a Cobra command tree under commands/. pkg/ for the public packages, including pkg/state. internal/ for the private ones, including the embedded web UI. templates/ for the Compose configs. And web/ held the React source, which got embedded into the binary at build time.
I could not have built this three weeks earlier. The JavaScript version wasn't wasted, it was the prototype that taught me what the real version had to be. Every CORS fight and every spawn() workaround was a requirement I was discovering the hard way. By the time I started the Go rewrite I wasn't starting over at all. I was finally building the thing I'd learned how to build.
The numbers, measured this time
An earlier draft of this post threw around hard figures: 50ms startup, 30MB resident versus 200MB on Node, sub-100ms responses, a thousand concurrent WebSocket connections. I couldn't point at a single one of them in the committed record, so I cut them and went and measured for real instead.
I pulled the archived v2-poc source, cross-compiled it, and ran it. Real numbers, with real caveats. This is the archived build rebuilt fresh, not the original August 2025 binary, which was never preserved. The binary size is a true linux/amd64 cross-compile. The startup and memory numbers were measured running the server on Apple Silicon, not Linux, because my Docker daemon wedged in the middle of the benchmark and I am not going to report a Linux runtime number I did not actually take.
- Binary size: 22.2 MB. One statically linked, stripped
linux/amd64file, verified as an ELF binary. No runtime to ship, nonode_modules, no build step on the target machine. That was the entire reason for the rewrite, and it is the one number that needs no caveat. - Cold start: about 37 milliseconds, median of ten runs, from process exec to the first
200on the health endpoint. That includes opening the LevelDB state store and binding the listener. - Idle memory: about 21 MB resident, median of ten, taken a couple of seconds after start while the server sat idle.
For reference, a bare Node process idles somewhere around 30 to 50 MB before Express and its dependencies even load, and the old backend was Express. I did not re-measure the Node build, so treat that as the well-known baseline it is, not a head-to-head I ran. The figures from the old draft turned out to be in the right neighborhood, but I could not stand behind them until I had actually run the thing.
What the PM knew that the programmer didn't
There is an old idea in software, Brooks in The Mythical Man-Month, that you will build one to throw away whether you plan to or not. The only real question is whether the first one teaches you enough to get the second one right.
The JavaScript MVP taught me the domain. Which APIs does homelab container management actually need. How deployment should flow. What a user wants on a dashboard at a glance. Those are product questions, and the only way to answer them is to build something and watch it fall short.
The Go rewrite took those answers and implemented them properly, with the Docker SDK instead of shelled-out CLI calls, real error handling, and one shippable file. Not because I had become a better programmer in three weeks. I still couldn't write Go without help. What I'd become was a better product owner who knew what to build.