Docker
When you answer “With Docker” during installation, your app, its database and a test mail inbox all run in containers. A container is a small, isolated Linux machine that Docker runs on your computer, built from a ready-made image (a snapshot of an operating system with a program installed, such as MySQL 8.4). Everyone on your team then runs exactly the same versions, and you never install MySQL or PostgreSQL yourself.
You keep typing the same commands as without Docker. node strut migrate on your computer is passed into the app container for you, so this page is mostly about what happens behind that, and what to do when it gets in the way.
The smallest example
Section titled “The smallest example”Create an app with Docker, then use it every day:
npm create strutvane@latest my-app -- --docker --yescd my-appnpm run devWhat you’ll see (something like this; the installer’s own lines are shown on Installation):
✔ Files written (33 files in /home/you/my-app)✔ Secrets generated in .env (APP_KEY, DB_PASSWORD, DB_ROOT_PASSWORD)✔ Ports checked (3000 free; 3306 free; 8025 free)✔ Containers running and healthy (app, db, mailpit) 15.3s✔ Dependencies installed with npm (added 13 packages)✔ Migrations run (3 new, 3 total); Admin created: admin@my-app.test; Database seeded✔ Git repository created (main, 1 commit)Then npm run dev starts the API and the UI inside the app container, and you open http://localhost:3000 on your computer as usual. Emails your app sends land in the test inbox at http://localhost:8025.
What runs where
Section titled “What runs where”The installer writes docker/compose.yaml, a Compose file: one file that lists the containers your app needs and how they connect. It has up to three services (Compose’s word for one kind of container):
| Service | Image | What it does |
|---|---|---|
app |
node:24 |
Your app. It idles and waits; every node strut command and npm run dev runs inside it. |
db |
mysql:8.4 (default) or postgres:18-alpine |
Your database. There is no db service with SQLite, which is a file in your project. |
mailpit |
axllent/mailpit:v1.33 |
A test inbox that catches every email your app sends, so nothing reaches real people. |
And three volumes (places where Docker keeps files):
| Volume | What’s in it |
|---|---|
..:/app |
Your project folder, shared with the container. You edit files on your computer; the container sees the change at once. |
node-modules |
Your installed packages, kept inside Docker. They are built for Linux, so they never clash with your own operating system. |
db-data |
The database’s data. It survives services:down. |
What runs inside the app container in Docker mode:
- the API and the React UI dev server (
npm run dev, which isnode strut dev); npm installand every other npm command (throughnode strut npm);migrate, seeding, queue workers, the scheduler and every othernode strutcommand.
What still runs on your computer: Docker itself, your editor, your browser, and strut.js, the small file that forwards commands. The strut.js forwarder (and the installer that writes it) is the only thing that needs Node.js on your computer. Nothing else does: your app’s code, its packages and its tools all live in the container.
How forwarding works
Section titled “How forwarding works”strut.js checks one thing first: did you choose Docker for this project? (The installer records the answer when it sets the project up.) If you did, and the command was typed on your computer rather than inside the container, it forwards it:
node strut migrate → docker compose -p my-app --env-file .env -f docker/compose.yaml exec app node strut migrateInside the container (where STRUTVANE_IN_CONTAINER=1 is set), the same file runs the command itself. Without Docker, it always runs on your computer. So one command works in both modes, and in every shell.
Two kinds of command always run on your computer, because they manage the containers themselves:
setup(npm run setup), which resumes the installer;- every
services:*command:services:up,services:down,services:statusandservices:logs.
Forwarded commands keep your terminal’s colours and input when you type them yourself, and switch to plain output (-T) in CI or when you pipe the output. The exit code comes back unchanged, so scripts and CI can rely on it.
Typical: a day’s work
Section titled “Typical: a day’s work”node strut services:up # start app, db and mailpit (once after a reboot)npm run dev # API + UI, in the containernode strut make:migration create_tags_table --seeder # in a second terminal: forwarded toonode strut migrateWhat you’ll see: the same output as without Docker. The only sign that Docker is involved is that it works without Node packages or a database on your computer.
Starting and stopping the services
Section titled “Starting and stopping the services”| Command | What it runs | When you need it |
|---|---|---|
node strut services:up |
docker compose up -d --wait |
After a reboot, or after services:down. It returns once every service is healthy (the database accepts connections). |
node strut services:down |
docker compose down |
To stop everything. Your data stays in the db-data volume. |
node strut services:down --volumes |
docker compose down -v |
To start over with an empty database. It asks you to confirm first. |
node strut services:status |
docker compose ps |
To see which services are running. |
node strut services:logs |
docker compose logs -f |
To follow the services’ output (add a service name, such as db, for one service). |
node strut db:shell |
a mysql or psql prompt in the db container |
To type SQL into your development database. |
node strut services:statusWhat you’ll see is Docker Compose’s own table, something like:
NAME IMAGE SERVICE STATUS PORTSmy-app-app-1 node:24 app Up 2 minutes 127.0.0.1:3000->3000/tcpmy-app-db-1 mysql:8.4 db Up 2 minutes (healthy) 127.0.0.1:3306->3306/tcpmy-app-mailpit-1 axllent/mailpit:v1.33 mailpit Up 2 minutes (healthy) 127.0.0.1:8025->8025/tcpEvery command uses your project’s own name (-p my-app, from COMPOSE_PROJECT_NAME), so it never touches another project’s containers.
Running npm, npx, node and a shell in the container
Section titled “Running npm, npx, node and a shell in the container”Like Sail, node strut passes four commands straight through to the app container:
| You type | It runs in the container | Use it for |
|---|---|---|
node strut npm <args> |
npm <args> |
Adding or updating packages |
node strut npx <args> |
npx <args> |
One-off tools |
node strut node <args> |
node <args> |
A quick script |
node strut shell |
bash (or sh when the image has no bash) |
Looking around inside the container |
Small: add a package
Section titled “Small: add a package”node strut npm install date-fnsWhat you’ll see: npm’s usual output. The package is installed into the node-modules volume, built for Linux, and package.json and package-lock.json change in your project folder as usual.
Typical: run a tool or a script
Section titled “Typical: run a tool or a script”node strut npx tsc --noEmitnode strut node scripts/report.tsWhat you’ll see: the tool’s output, and its exit code passed back to your shell. node strut npx tsc --noEmit exits with 0 when there are no type errors and with a non-zero code when there are, exactly as npx tsc would, so CI fails when it should.
Advanced: arguments arrive exactly as you typed them
Section titled “Advanced: arguments arrive exactly as you typed them”Arguments go to the container as a list, never through a shell on the way, so characters that shells treat specially arrive untouched. The prototype tests a&b, $(...) and %PATH%:
node strut node -e "console.log(process.argv.slice(1))" "a&b" "100%PATH%"What you’ll see:
[ 'a&b', '100%PATH%' ]Your own shell still reads the line first, so quote anything it would change, as you would for any command.
Without Docker, the same four commands run on your computer, so scripts that use them work in both modes.
Every port a container publishes is bound to 127.0.0.1, so only your own computer can reach it. Nobody else on your Wi-Fi can open your app, your database or your test inbox.
.env key |
Default | What it is |
|---|---|---|
APP_PORT |
3000 |
The app (API and UI on one port, hot reload included) |
FORWARD_DB_PORT |
3306 (MySQL), 5432 (PostgreSQL) |
The database, as seen from your computer (for a database GUI) |
FORWARD_MAILPIT_PORT |
8025 |
The test inbox |
During installation, the installer checks each port first. When one is in use, it picks the next free one and writes it into .env (“port 3306 is in use; using 3307”). Mailpit’s mail port (1025) is never published: only the app talks to it, over Docker’s own network.
Inside the container the dev server listens on 0.0.0.0 (APP_HOST), because that is the only way traffic from your computer reaches it. A Host allowlist still answers any request whose Host header isn’t localhost, 127.0.0.1, [::1] or your APP_URL’s host with 400, as Laravel does, which blocks DNS-rebinding tricks.
The .env keys in Docker mode
Section titled “The .env keys in Docker mode”The installer writes these for you. The app reaches other services by their service name (db, mailpit), because inside Docker’s network that is their address:
APP_PORT=3000
DB_CONNECTION=mysqlDB_HOST=dbDB_PORT=3306FORWARD_DB_PORT=3306DB_DATABASE=my_appDB_TEST_DATABASE=my_app_testDB_USERNAME=my_appDB_PASSWORD=generated-for-youDB_ROOT_PASSWORD=generated-for-you
MAIL_MAILER=smtpMAIL_HOST=mailpitMAIL_PORT=1025FORWARD_MAILPIT_PORT=8025
COMPOSE_PROJECT_NAME=my-appSTRUT_UID=1000STRUT_GID=1000DB_PORTis the port inside Docker’s network;FORWARD_DB_PORTis the one on your computer. A database GUI on your computer connects to127.0.0.1:FORWARD_DB_PORT.DB_ROOT_PASSWORDis the database image’s administrator password. It’s generated and your app never uses it.STRUT_UIDandSTRUT_GIDare the user the app container runs as (see Platform notes).- Every password is generated into
.envonly, never into.env.example, and never on a command line. See Configuration for every other key.
PostgreSQL: two database users
Section titled “PostgreSQL: two database users”With PostgreSQL, the installer creates two roles (database users) on the first start:
.env key |
Role | Used for |
|---|---|---|
DB_MIGRATION_USERNAME |
my_app_owner |
Running migrations. It owns the tables. |
DB_USERNAME |
my_app_app |
Everything else. It is not a superuser and can’t bypass row-level security. |
Why two: PostgreSQL’s row-level security (which keeps teams apart, see Security Features) doesn’t apply to a table’s owner or to a superuser. Running the app as a plain role means the database itself enforces the rule.
The test database
Section titled “The test database”A second database, DB_TEST_DATABASE (my_app_test), is created next to the development one on the first start, so npm test never touches your local data.
Teammates and a fresh clone
Section titled “Teammates and a fresh clone”The Docker files and .env are git-ignored, so a teammate who clones the project has neither. What they do have is the committed strutvane.json, which holds every installer answer. They run:
git clone https://github.com/acme/my-app.gitcd my-appnpm run setupnpm run setup works from strutvane.json alone: it writes the Docker setup and .env with fresh secrets, starts the containers, installs packages, migrates and seeds. The local progress file (.strutvane/local/setup.json, git-ignored) is optional; when it’s there, setup skips the steps already done.
Docker or not: switching later
Section titled “Docker or not: switching later”Platform notes
Section titled “Platform notes”-
Install Docker Desktop and start it before
npm createornode strut services:up. If it isn’t installed or isn’t running, the installer offers, in this order: use your own database server (XAMPP, a local install or a remote server), start Docker and retry, or continue without Docker on SQLite. See Installation. -
Keep the project inside WSL2 (for example
\\wsl$\Ubuntu\home\you\my-app) for fast file watching. On a Windows folder (C:\Users\you\my-app), file-change events don’t cross into the container reliably, so the dev server polls for changes (CHOKIDAR_USEPOLLING=1,STRUT_WATCH_POLLING=1). That works, but reloads can lag. (WSL2 is recommended; its effect on watching wasn’t measured in the prototype.) -
Line endings: shell scripts you commit and run inside the container must keep
LFline endings. If git converts them toCRLF(core.autocrlf=true), Linux can’t run them ($'\r': command not found). Usegit config core.autocrlf inputfor the project, or work inside WSL2. The installer writes its own Docker files withLF. -
PowerShell, cmd and Windows Terminal all work:
node strutneeds no wrapper and no execution-policy change. -
Install Docker Desktop (or another Docker engine) and start it first.
-
Docker Desktop maps file ownership for you, so files the container writes are yours.
-
File events across the shared folder can be unreliable, so the dev server polls for changes, as on Windows.
-
Install Docker Engine and the Compose plugin.
-
If Docker says
permission deniedondocker.sock, add yourself to thedockergroup, then log out and back in:Terminal window sudo usermod -aG docker $USER -
The app container runs as your user id (
STRUT_UID/STRUT_GIDfrom your account), so files it writes into your project are yours, not root’s. (This is written and unit-tested, but the prototype was only run on Windows.)
The production Dockerfile
Section titled “The production Dockerfile”Everything above is for development. For production, many hosts (Kubernetes, Fly, Cloud Run, ECS) want a Docker image: a packaged copy of your built app that the host runs. The installer can write a secure one for you, and this one you commit.
You ask for it in one of three ways:
npm create strutvane@latest my-app -- --deploy docker # question 35 "Where will you deploy?" → Docker imagenode strut docker:prod # later, in an existing appor by picking Docker image when the installer asks “Where will you deploy?”.
It writes:
Dockerfile, in three stages (separate build steps whose leftovers are thrown away): one builds your app withnpm ci --ignore-scriptsandnode strut build, one installs production dependencies only, and the last copies onlybuild/and those dependencies into a cleannode:24-bookworm-slimimage. The final image runs as the non-rootnodeuser, exposes port 3000 and setsLOG_CHANNEL=stderrandLOG_FORMAT=json, so your host collects the logs as one JSON object per line (see Logging). ItsHEALTHCHECKcalls/up, the health route every app has: it answers200 {"status":"ok"}toGETandHEAD, and stays reachable during maintenance mode..dockerignore, which keeps.env*,.git,node_modules,storage/and tests (plusdocker/,.strutvane/,.devcontainer/,.vscode/and local SQLite files) out of the build, so no secret can end up in the image.deploy/README.md, the recipe:
docker build -t my-app .docker run -p 3000:3000 --env APP_KEY --env APP_URL --env DB_HOST my-app--env APP_KEY with no value passes the variable from your own shell’s environment, so the key never appears on the command line or in your shell history. Create a production key once with node strut key:generate and keep it in your host’s secrets.
What you’ll see: Docker builds the three stages, then the container starts and GET /up answers {"status":"ok"}. Settings reach the container as environment variables from your host’s dashboard (the keys are listed in .env.example); never copy .env into an image.
Run migrations as a separate release step, not when each container starts. In production, node strut migrate asks for confirmation unless you pass --force, as in Laravel, so the recipe uses node strut migrate --force. See Deployment.
/up only tells you the process is alive. A readiness check that also tests the database (/ready) comes in 0.3.
The dev container
Section titled “The dev container”A dev container is a Docker setup your editor opens directly: GitHub Codespaces and VS Code Dev Containers start it, and you work inside it with nothing installed on your computer. It’s also opt-in and committed, so the whole team gets it:
npm create strutvane@latest my-app -- --dev-containeror answer yes to “Add a dev container for Codespaces?” (part of question 36, editor setup; the default is no).
It writes .devcontainer/devcontainer.json and .devcontainer/compose.yaml: one app service on node:24-bookworm, running as the node user, which runs npm ci --ignore-scripts when it’s created and forwards port 3000. It contains no secrets: it reads ../.env at runtime if there is one (create it with npm run setup, or use Codespaces secrets).
Common mistakes
Section titled “Common mistakes”“The app container is not running”
Section titled ““The app container is not running””The app container is not running. Start it with: node strut services:upWhy: Docker mode forwards commands into the app container, and it isn’t started (after a reboot, or after services:down).
Fix:
node strut services:up“Docker is not answering”
Section titled ““Docker is not answering””Docker is not answering (Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?). Start Docker Desktop, then: node strut services:upWhy: Docker Desktop (or the Docker engine) isn’t running. The text in brackets is Docker’s own message and varies by system. Fix: start Docker Desktop, wait until it says it’s running, then:
node strut services:up“permission denied” on docker.sock (Linux)
Section titled ““permission denied” on docker.sock (Linux)”Docker is not answering (permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock). Start Docker Desktop, then: node strut services:upWhy: your user isn’t allowed to talk to Docker. (Docker’s part of the message is shortened here; it continues with the socket address.)
Fix: join the docker group, log out and back in, then retry:
sudo usermod -aG docker $USER“Docker was not found”
Section titled ““Docker was not found””Docker was not found. Install Docker Desktop (https://docs.docker.com/get-docker/), or run without Docker.Why: the docker program isn’t on your PATH. For safety, node strut only looks in absolute PATH folders, never in the current folder.
Fix: install Docker Desktop (or Docker Engine on Linux), open a new terminal and check:
docker --version“COMPOSE_PROJECT_NAME is missing in .env”
Section titled ““COMPOSE_PROJECT_NAME is missing in .env””COMPOSE_PROJECT_NAME is missing in .env. Run: npm run setupWhy: .env is missing or was replaced, for example after a fresh clone or copying .env.example by hand.
Fix:
npm run setupservices:up says a port is already allocated
Section titled “services:up says a port is already allocated”Error response from daemon: ... Bind for 127.0.0.1:3306 failed: port is already allocatedWhy: something else (often a MySQL installed on your computer, or another project’s containers) uses that port. The installer moves ports only while it runs; afterwards the ports in .env stay as they are. (This is Docker’s message, so the exact wording depends on your Docker version.)
Fix: pick a free port in .env, then start again:
FORWARD_DB_PORT=3307node strut services:upI ran npm install on my computer and the app can’t find the package
Section titled “I ran npm install on my computer and the app can’t find the package”Why: in Docker mode the app’s packages live in the node-modules volume inside Docker. npm install on your computer writes to your computer’s folder, which the container doesn’t use, and builds native packages for the wrong operating system.
Fix: install through the container:
node strut npm install date-fnsSaving a file doesn’t reload the app on Windows
Section titled “Saving a file doesn’t reload the app on Windows”Why: the project sits on a Windows drive, so file-change events don’t reach the container and the dev server falls back to polling, which can lag. Fix: move the project into WSL2 and work from there:
cd ~git clone https://github.com/acme/my-app.gitcd my-appnpm run setupNext steps
Section titled “Next steps”- Installation: the Docker question and everything else the installer asks.
- Configuration: every
.envkey. - CLI Reference: every
node strutcommand. - Deployment: taking the app to production.