Deployment
Deploying means taking the app that runs on your laptop and running it on a server where your users can reach it. With Strutvane that’s four steps: build the app into build/, give the server its settings (environment variables), migrate the database, and start build/server.js. This page walks through each, for a plain Node host and for a Docker image, and ends with a checklist to go through before launch.
The smallest example
Section titled “The smallest example”On any server with Node 24.3 or newer, from a fresh copy of your repository:
npm ci --ignore-scripts # exact dependencies from package-lock.json, no install scriptsnode strut build # bundles the server and the UI into build/node strut migrate --force # applies new migrations (--force: yes, this is production)npm start # runs node build/server.jsWhat you’ll see (something like this):
Built build/server.js (start it with: npm start) ✔ Migrations run (2 new, 14 total)Strutvane is listening on http://0.0.0.0:3000 (production)Check it’s alive:
curl -i http://your-server:3000/upWhat you’ll see:
HTTP/1.1 200 OKcontent-type: application/json
{"status":"ok"}Your load balancer or host calls /up the same way.
This is exactly the recipe the installer writes to deploy/README.md when you pick “Any Node host”.
Step 1: build
Section titled “Step 1: build”node strut buildbuild/ then holds everything the server needs: the compiled server (build/server.js) and the React UI’s static files. The server runs from build/ with only production dependencies; it doesn’t need the CLI, TypeScript, Vite or any dev tool. Build once and copy build/ to several servers, or build on each; both work.
Build on the same Node major version you run in production, so native details match.
Step 2: production settings
Section titled “Step 2: production settings”Settings come from environment variables, set in your host’s dashboard (or a systemd unit, or your container platform). .env.example lists every key your app reads. Never upload .env, and never put secrets in the image or the repository.
The keys that must change for production:
| Key | Production value | Why |
|---|---|---|
APP_ENV |
production |
turns off developer pages and hints |
APP_DEBUG |
false |
the app refuses to start with APP_DEBUG=true in production unless you pass --force-debug |
APP_KEY |
a new key, made with node strut key:generate (never the development one) |
signs and encrypts everything. The same on every server |
APP_PREVIOUS_KEYS |
old keys after a rotation | keeps old cookies, tokens and encrypted values working |
APP_URL |
https://app.example.com |
links in mails, cookie security, CSRF origin checks |
DB_* |
your production database | — |
MAIL_* |
your production mailer | see Mail |
LOG_CHANNEL, LOG_FORMAT |
stderr and json in containers; daily on a VPS |
let the platform collect logs |
The app checks every setting at start-up and lists all problems at once, so a missing key fails the deploy instead of the first request:
✖ The app refuses to start: APP_DEBUG=true with APP_ENV=production.→ Set APP_DEBUG=false in the production environment. To start anyway for a short investigation, pass --force-debug (the debug page stays off in production either way).Want to commit production settings safely? node strut env:encrypt encrypts .env.production so the encrypted file can live in Git; the server decrypts it with a key you keep in the host’s secrets (designed; see Configuration).
Step 3: migrate safely
Section titled “Step 3: migrate safely”node strut migrate --force --isolated- In production,
migrateasks for confirmation, like Laravel;--forceanswers yes for you, which a deploy script needs because nobody is there to type it. (--seedin production also needs--force; nothing is seeded there otherwise.) --isolatedtakes a lock, so when several servers deploy at the same moment, only one migrates and the others wait.- PostgreSQL and SQLite run each migration in a transaction: a failure leaves nothing behind.
- MySQL commits schema changes as it goes. If a migration fails halfway,
migratetells you exactly what was applied and how to recover.
Before a risky change, preview the SQL:
node strut migrate --pretendThe pre-flight check flags dangerous changes before anything runs: a NOT NULL column without a default on a table with rows, a drop that looks like a rename, a dropped column still used in resources/ui. See Migrations.
Order matters for zero-downtime deploys: migrate before switching traffic to the new code, and make each migration safe for the old code too (add columns first, remove them in a later release).
Step 4: run it
Section titled “Step 4: run it”npm startThat runs node build/server.js. Keep it running with whatever your host offers: the platform’s process manager (Railway, Render, Fly, Cloud Run, Kubernetes), or systemd on a VPS:
[Unit]Description=my-appAfter=network.target
[Service]User=myappWorkingDirectory=/srv/my-appEnvironmentFile=/etc/my-app/envExecStart=/usr/bin/node build/server.jsRestart=alwaysKillSignal=SIGTERMTimeoutStopSec=30
[Install]WantedBy=multi-user.targetsudo systemctl enable --now my-appGraceful shutdown
Section titled “Graceful shutdown”When the host stops or replaces your app, it sends SIGTERM. The server then stops accepting new requests, lets the requests in flight finish, flushes the log, closes database connections, and exits. Give it time: TimeoutStopSec=30 above, or your platform’s grace period. Don’t kill -9 it unless it’s stuck.
Behind a proxy or load balancer
Section titled “Behind a proxy or load balancer”Most hosts put a proxy in front of your app that handles HTTPS. Two settings then matter:
- Trusted proxies: tell the app which proxies may set
X-Forwarded-ForandX-Forwarded-Proto. Without it, every visitor seems to have the proxy’s IP, so rate limits hit everyone at once. - Trusted hosts: the app answers only for your own domain names, and refuses others with
400.
Both are covered in Security Features.
More than one server
Section titled “More than one server”- Use the same
APP_KEY(andAPP_PREVIOUS_KEYS) everywhere, or sessions and signed links made by one server fail on another. - Rate limits and lockouts live in the cache store (the database by default, Redis if you chose it), so they hold across servers. A per-process store would multiply every limit by the number of servers.
- Files written to the local disk exist only on that server. Use shared storage or a cloud disk (
@strutvane/files, planned) when several servers serve uploads. - Or run several Node processes on one machine:
node strut serve --workers=N(cluster mode) is coming before 1.0.
Health checks: /up
Section titled “Health checks: /up”/up answers 200 {"status":"ok"} to GET and HEAD as soon as the app is running, and says nothing else (no versions, no settings), so it’s safe to leave public. It stays reachable during maintenance mode, so your platform doesn’t restart a container that’s down on purpose. Point your host’s health check, your load balancer and the Dockerfile’s HEALTHCHECK at it. (The installer prototype’s generated route still answers the text up; the JSON answer is decided for 0.2.)
Deploying as a Docker image
Section titled “Deploying as a Docker image”Pick Docker image when the installer asks “Where will you deploy?”, or run node strut docker:prod later. You get three committed files:
Dockerfile, which builds in three stages: build, production dependencies only, then a clean runtime image;.dockerignore, which keeps.env*,.git,node_modules,storage/, tests and.strutvane/local/out of the image (the rest of.strutvane/is generated code the build needs);deploy/README.md, the recipe.
The generated Dockerfile (from the installer prototype, without its prototype-only stubs/ lines and with some comments shortened):
# syntax=docker/dockerfile:1# Secrets are never copied in: .dockerignore excludes every .env* file, and the platform passes# settings as environment variables when the container starts. Regenerate: node strut docker:prod
# 1. Build: install everything (dev dependencies too) and compile to build/.FROM node:24-bookworm-slim AS buildWORKDIR /appCOPY package.json package-lock.json .npmrc ./RUN npm ci --ignore-scriptsCOPY . .RUN node strut build
# 2. Production dependencies only.FROM node:24-bookworm-slim AS depsWORKDIR /appCOPY package.json package-lock.json .npmrc ./RUN npm ci --omit=dev --ignore-scripts
# 3. Run: only build/ and production dependencies, as the image's non-root "node" user.FROM node:24-bookworm-slimENV NODE_ENV=productionWORKDIR /appCOPY --from=deps --chown=node:node /app/node_modules ./node_modulesCOPY --from=build --chown=node:node /app/build ./buildCOPY --chown=node:node package.json ./USER nodeEXPOSE 3000HEALTHCHECK --interval=30s --timeout=3s --start-period=15s --retries=3 \ CMD node -e "fetch('http://127.0.0.1:' + (process.env.APP_PORT || 3000) + '/up').then((r) => process.exit(r.ok ? 0 : 1), () => process.exit(1))"CMD ["node", "build/server.js"]Build and run it:
-
Generate a production key once, and store it in your host’s secret settings (never in the image or in Git):
Terminal window node strut key:generate --show(
--showprints the key instead of writing it to.env; the flag name follows Laravel and isn’t final.) -
Build the image and run it, passing settings from your environment:
Terminal window docker build -t my-app .docker run -p 3000:3000 --env APP_KEY --env DB_HOST --env APP_URL my-app--env APP_KEYwith no value copiesAPP_KEYfrom your shell’s environment (set it from your secrets manager first), so the key never appears in your shell history or in this command.
What you’ll see: Docker builds the three stages, then docker ps shows the container as healthy once /up answers.
Why it’s built this way:
| Choice | Protects against |
|---|---|
non-root node user |
a bug in the app becoming root inside the container |
only build/ and production dependencies |
a bigger attack surface and image (no sources, tests, dev tools) |
.env* excluded, settings at runtime |
secrets baked into image layers, readable by anyone who pulls the image |
npm ci --ignore-scripts |
dependency install scripts running during the build |
HEALTHCHECK on /up |
a hung container staying in rotation |
Logs: in a container, write logs to the process output as JSON lines, and let the platform collect them:
LOG_CHANNEL=stderrLOG_FORMAT=jsonThe generated Dockerfile sets these two (decided for 0.2; the prototype’s template doesn’t yet, so set them in the environment for now). See Logging.
Run migrations as a separate step, not when each container starts: a one-off job (docker run my-app node strut migrate --force --isolated), a Kubernetes Job, or your platform’s release command. Note that the runtime image has only production dependencies; node strut migrate must work from them, which the framework’s packaging (it ships compiled JavaScript) is designed for.
Persistent files: the container’s own disk is thrown away on every deploy. Mount a volume at storage/ or use a cloud disk.
Every deploy, in order
Section titled “Every deploy, in order”- Build (or pull the new image).
- Optional:
node strut down --secret=<a long random string>for maintenance mode on risky deploys. See Maintenance Mode. node strut migrate --force --isolated.node strut optimizeto cache config, routes and events for faster start-up. See Optimization.- Start the new version; let the old one shut down gracefully.
- From 0.3:
node strut queue:restart, so workers pick up the new code after their current job. node strut upif you used maintenance mode.- Watch
/up, the logs and your error rate for a few minutes.
Rolling back: deploy the previous build or image. Only roll a migration back (node strut migrate:rollback) if it can’t work with the old code, and only after checking what it drops.
Background work (coming in 0.3)
Section titled “Background work (coming in 0.3)”Production apps that use queues or the scheduler run extra processes next to the web server:
- one or more queue workers, restarted on deploy (
queue:restart); - the scheduler: one cron entry calling
node strut schedule:runevery minute, or anode strut schedule:workprocess.
Each extra process writes its own log file, so files never get mixed up.
Production checklist
Section titled “Production checklist”Go through this before launch, and again before big releases. It follows Strutvane’s production readiness protocol, applied to your app.
Settings and secrets
-
APP_ENV=production,APP_DEBUG=false. - A fresh
APP_KEY(not the development one), the same on every server, stored in a password manager. -
APP_URLishttps://…(over HTTPS the session cookie becomes__Host-strutvane_session, which a sibling subdomain can’t set). - No secrets in Git, in
.env.exampleor in the image;.env*is in.dockerignore. -
node strut security:checkpasses (it flags debug on, a missing key, a non-HTTPSAPP_URL, insecure cookies, CORS*with credentials, a weak CSP,npm audithighs and exposed/_strutvane/*tools).
Data
- Migrations applied with
--isolated;migrate --pretendreviewed for risky changes. - Database backups run and a restore has been tested.
- With teams on PostgreSQL: row-level security is on (
tenancyAuditreports nothing). - Uploaded files live on a persistent volume or cloud disk.
Traffic
- HTTPS everywhere; trusted proxies and trusted hosts configured.
- Health checks point at
/up. - Rate limits use the shared cache store, not memory.
Operations
- Logs reach your platform (
stderr+jsonin containers,dailywith retention on a VPS), and nothing secret is in them. - A rollback plan: the previous build or image is kept.
- Graceful shutdown has time to finish (30 seconds or more).
-
npm audit --omit=devshows no high or critical issues. - Mail: SPF, DKIM and DMARC set for your sending domain.
Platform notes
Section titled “Platform notes”- Building on Windows, deploying to Linux: fine;
build/is plain JavaScript. Usenpm cion the server so platform-specific packages match Linux. - macOS or Windows with Docker Desktop:
docker buildworks the same; images target Linux. - Node version: Node 24.3 or newer (earlier 24.x releases break arguments in PowerShell); the image pins Node 24.
Common mistakes
Section titled “Common mistakes”The app won’t start in production: “APP_DEBUG=true with APP_ENV=production”
Section titled “The app won’t start in production: “APP_DEBUG=true with APP_ENV=production””✖ The app refuses to start: APP_DEBUG=true with APP_ENV=production.Why: the debug setting from development reached production. The app refuses to start rather than risk showing debug details.
Fix: set APP_DEBUG=false in the production environment.
Everyone was signed out after the deploy
Section titled “Everyone was signed out after the deploy”Why: the new servers got a different APP_KEY.
Fix: use the same APP_KEY everywhere. When you do rotate it, move the old one to APP_PREVIOUS_KEYS (node strut key:rotate).
The container is “unhealthy” and keeps restarting
Section titled “The container is “unhealthy” and keeps restarting”Why: /up doesn’t answer: the app failed to start (look at the container’s logs for the start-up error), or it listens on another port than the health check calls.
Fix: read docker logs <container>, and make APP_PORT match the port you expose.
Uploaded files disappear after every deploy
Section titled “Uploaded files disappear after every deploy”Why: they were written inside the container.
Fix: mount a volume at storage/, or use a cloud disk.
Every visitor is rate-limited at once
Section titled “Every visitor is rate-limited at once”Why: the app sees the proxy’s IP for everyone, because trusted proxies aren’t configured. Fix: configure trusted proxies (see Security Features).
Links in mails point at localhost
Section titled “Links in mails point at localhost”Why: APP_URL still has its development value.
Fix: set APP_URL=https://app.example.com in production.
Next steps
Section titled “Next steps”- Docker: local Docker mode and the production image.
- Configuration: every
.envkey. - Security Features: proxies, hosts, headers and
security:check. - Logging: logs in production and containers.