Embed and deploy

The last step turns the two halves into one file. A Go binary can carry arbitrary files with a compiler directive, and the static file server that serves them is in the standard library, so deployment is a copy: no Node on the server, no nginx, no directory of assets to keep in sync with the binary.

The embed directive

The package web exists only to hold the directive. all:dist includes every file under dist, including the ones whose names start with an underscore or a dot, which a bare dist pattern would skip; a Vite bundle has neither, but a project that adds one should not discover the difference in production.

// Package web holds the built frontend that goes into the binary. package web import "embed" // Assets is the Vite build output copied into the binary. // //go:embed all:dist var Assets embed.FS

The server

main opens the database, takes the embedded file system, mounts the API under /api/ and the page under /, and wraps the whole thing in the CORS middleware. The timeouts are set on the server rather than left at zero, and Shutdown gets five seconds when the signal arrives.

// Command server serves the notes API and the built frontend. package main import ( "context" "errors" "flag" "io/fs" "log/slog" "net/http" "os" "os/signal" "syscall" "time" "example.com/notesweb/internal/notes" "example.com/notesweb/web" ) func main() { addr := flag.String("addr", ":8080", "listen address") dbPath := flag.String("db", "notes.db", "SQLite database file") origin := flag.String("origin", "http://localhost:5173", "origin allowed by CORS") flag.Parse() log := slog.New(slog.NewTextHandler(os.Stderr, nil)) store, err := notes.OpenSQLite(*dbPath) if err != nil { log.Error("open database", "err", err) os.Exit(1) } defer store.Close() dist, err := fs.Sub(web.Assets, "dist") if err != nil { log.Error("embed frontend", "err", err) os.Exit(1) } mux := http.NewServeMux() mux.Handle("/api/", notes.Handler(store, log)) mux.Handle("/", spa(dist)) server := &http.Server{ Addr: *addr, Handler: notes.CORS(*origin, mux), ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 30 * time.Second, WriteTimeout: 30 * time.Second, IdleTimeout: 60 * time.Second, } go func() { log.Info("listening", "addr", *addr, "db", *dbPath) if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) { log.Error("listen", "err", err) os.Exit(1) } }() ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() <-ctx.Done() shutdown, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() if err := server.Shutdown(shutdown); err != nil { log.Error("shutdown", "err", err) } log.Info("stopped") } // spa serves a file from dist, or index.html for a client-side route. func spa(dist fs.FS) http.Handler { files := http.FileServerFS(dist) return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { if _, err := fs.Stat(dist, trimSlash(r.URL.Path)); err != nil { r.URL.Path = "/" } files.ServeHTTP(w, r) }) } func trimSlash(path string) string { if path == "/" { return "index.html" } return path[1:] }

The fallback is the part a single-page app needs: a request for /notes/42 is a client-side route, not a file, so the handler checks whether the path exists in the embedded system and serves index.html when it does not. Without it, a refresh on a deep link is a 404 from the file server, which is the most common bug of a first SPA deployment.

One binary, run here

The build disables cgo, which matters because the SQLite driver is pure Go and nothing else needs a C compiler. The result is a static executable of about sixteen megabytes, and it runs from any directory with no source tree and no Node modules beside it:

CGO_ENABLED=0 go build -trimpath -o notes ./cmd/server
ls -lh notes
file notes

-rwxr-xr-x 1 agent agent 16M Nov 18 04:09 notes
notes: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, Go BuildID=P2x2icrNDghDCikJPl4b/3uR8Hx7ueu65QJ2IoJJm/B3eECjPEAJcTpcMplbPE/-Ti9pf6aXyBLYWcoAiNR, BuildID[sha1]=f9d3923aa3ddb9c4481974591b62f4c4a98ecd38, with debug_info, not stripped

The binary was copied to a bare directory and started there, with its database in /tmp:

./notes -addr 127.0.0.1:18084 -db /tmp/single.db
curl -s http://127.0.0.1:18084/api/notes
curl -s -o /dev/null -w 'index status %{http_code}\n' http://127.0.0.1:18084/

[]
index status 200
time=2026-11-18T04:10:00.760Z level=INFO msg=listening addr=127.0.0.1:18084 db=/tmp/single.db
time=2026-11-18T04:10:01.682Z level=INFO msg=stopped

The two log lines are the start and the graceful stop after SIGINT, and the 200 is the page served from inside the executable. The real bundle from the frontend page adds 225.46 kB of JavaScript and 0.42 kB of CSS, so a binary built with it stays at about sixteen megabytes.

The built frontend

The frontend was built in the node:22-bookworm image with Node v22.23.3 and npm 10.9.9, and the whole output is on the frontend page: 30 modules, a 225.46 kB script and a 0.42 kB stylesheet. The build wrote the directory this directive expects, with a content hash in each asset name:

web/dist/
index.html 0.40 kB
assets/
index-<hash>.js 225.46 kB
index-<hash>.css 0.42 kB

The hashes are what lets a browser cache the files forever; index.html is the only file that must not be cached, because it names them. The binary on this page was built and run in the course container with a hand-written web/dist of the same shape, because the built files were produced in another image; the go build below embeds whichever directory is there, and the frontend page says how the real one is produced.

The steps to build and run

Two commands build the frontend, and two build and run the product. The first two ran in node:22-bookworm; the last two ran in this container with the placeholder directory, and they are the same commands a reader runs with the real one:

cd frontend && npm install
npm run build
cd .. && CGO_ENABLED=0 go build -o notes ./cmd/server
./notes -addr 127.0.0.1:8080 -db notes.db

After the real build, the checks are the ones a deployment needs: the page at http://127.0.0.1:8080/ loads its script from /assets/, a create and a list work through the page itself, a refresh on a route that is not a file returns index.html and not a 404, and the binary still runs after the frontend and web/dist directories are moved away.

A Dockerfile sketch

The image has two stages, one with Node to build the frontend and one with Go to build the binary. A Dockerfile like this is the usual way to ship it. It was not built here: this container has no Docker daemon and no network to a registry, so the file is a sketch of the steps above, not a tested recipe.

FROM node:22-alpine AS frontend WORKDIR /src/frontend COPY frontend/package*.json ./ RUN npm ci COPY frontend/ ./ RUN npm run build FROM golang:1.26-alpine AS build WORKDIR /src COPY go.mod go.sum ./ RUN go mod download COPY . . COPY --from=frontend /src/web/dist ./web/dist RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/notes ./cmd/server FROM scratch COPY --from=build /out/notes /notes EXPOSE 8080 ENTRYPOINT ["/notes", "-addr", ":8080", "-db", "/data/notes.db"]

The scratch stage works because the binary is static and the SQLite driver is pure Go; there is no shell and no libc in the image, which is also why the database path must be a mounted volume and the process must handle a missing directory itself. A production version adds a non-root user, a health check and a migration step, and those are lessons of their own.

The Go lesson behind the directive is embed: files inside the binary, and the HTTP lessons are an HTTP server and graceful shutdown. The previous page of this group is the React frontend.

The Go code on this page was run with go 1.26.10 and modernc.org/sqlite v1.62.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container. The frontend was built in the node:22-bookworm image with Node v22.23.3, npm 10.9.9, vite 6.4.6, react 19.3.1, react-dom 19.3.1, typescript 5.7.3, @vitejs/plugin-react 4.7.0, @types/react 19.3.0 and @types/react-dom 19.3.0. The Docker build of the Dockerfile below is still not run here: this container has no Docker daemon and no network to a registry.

Article author: Arthur Isaev