Deployment
Build one binary
nexus build -o my-appThis runs the Vite build (and the SSR build, if there is one) when the app has a frontend, then runs go build, which embeds web/dist. The build is pure Go, so cross-compiling works as usual:
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 nexus build -o my-appnexus build ./cmd/server builds a main package other than the current directory.
Run it
NEXUS_ENVIRONMENT=production ./my-appNEXUS_ENVIRONMENT=productionoverrides theenvironment = "development"that scaffolds put innexus.toml. Development mode follows a Vite hot file and writes SDK files, and production does neither.- Ship
nexus.tomlbeside the binary, or point at it withNEXUS_CONFIG. - Put secrets in environment variables. Reference them as
${VAR}innexus.toml, or rely on the automatic override (db.password→DB_PASSWORD). - Node.js is not needed, unless you run an Inertia SSR server:
node web/dist/ssr/ssr.js.
A minimal container image:
FROM gcr.io/distroless/static
COPY my-app nexus.toml /app/
WORKDIR /app
ENV NEXUS_ENVIRONMENT=production
ENTRYPOINT ["/app/my-app"]Production checklist
[runtime]
introspection = false # the default: /__nexus returns 404
introspection_networks = ["10.0.0.0/8"] # except from your operators' network
[runtime.server]
max_body_bytes = 33554432 # request-body cap (32MB, the default)
shutdown_timeout = "10s" # graceful drain on SIGTERM (the default)
[runtime.middleware.security]
hsts_max_age = 31536000 # once you serve https- The dashboard is closed unless introspection is on.
introspection_networksmatches the real TCP peer address, notX-Forwarded-For. - Request bodies are capped at 32MB (
max_body_bytes;-1turns the cap off). Over the limit is a 413. Move one endpoint's cap withnexus.MaxBody(n). - Timeouts:
read_timeoutandwrite_timeoutare off by default, because they would cut off large uploads and streams; bound one endpoint withnexus.Timeout(d)instead. Headers must arrive within 10s, andidle_timeoutdefaults to 120s. - Shutdown: on SIGINT or SIGTERM, in-flight requests get
shutdown_timeoutto finish. Their contexts are then cancelled. - WebSockets are same-origin by default. List other frontends in
[runtime.websocket] allowed_origins. - The client SDK:
sdk = truepublishes your API map. Vendor it withnexus client --outif you'd rather not.
Listeners and scopes
Serve different routes on different addresses:
[runtime.server]
addr = ":8080" # public
[runtime.server.listeners.admin]
addr = "127.0.0.1:7000"
scope = "admin"| Scope | Serves |
|---|---|
public | Your routes. /__nexus is hidden, except /__nexus/health and /__nexus/ready. |
internal | The same as public. Use it for peer services and load-balancer probes. |
admin | Everything, including the dashboard. Bind it to a private address. |
The introspection gate still applies on every listener. A common setup is introspection = true with a public listener, which hides the dashboard, and an admin listener on a private address, which serves it.
Health
/__nexus/health (200 when the app is alive) and /__nexus/ready (200 when it and every tracked peer are ready) answer even when introspection is off, so orchestrator probes work against a locked-down binary.