Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Installation

View as Markdownllms.txt

Creating a Strutvane app is one command. The installer (the small program npm create downloads and runs) asks what you need, then writes the project, installs everything, starts the database, creates your tables and the first admin user, and makes a first git commit. When it finishes, the app works.

This page explains every question, every flag, every step, and what to do when something gets in the way.

You need:

  1. Node.js 24.3 or newer. It comes with npm, the only package manager Strutvane uses. Check your version:

    Terminal window
    node --version

    Earlier 24.x releases break command-line arguments in PowerShell, so 24.3 is the minimum. If you see something lower than v24.3.0, install the current LTS from nodejs.org.

  2. Docker Desktop (recommended, not required). New apps use MySQL by default. With Docker, your app, MySQL and a test mail inbox all run in containers, so you never install MySQL yourself. Without Docker, the app runs on your computer with SQLite (nothing to install) or with your own database server. See Docker.

  3. Git (optional). If it’s installed, your project starts with a first commit.

Run this in the folder where you keep your projects:

Terminal window
npm create strutvane@latest my-app

my-app is the folder name. npm may ask “Ok to proceed?” the first time: answer y. Then press Enter on every question to accept the defaults.

What you’ll see at the end (something like this; the password line appears only in a real terminal):

── Ready ───────────────────────────────────────────────────────
App http://localhost:3000
Database MySQL in Docker, 127.0.0.1:3306/my_app
Design crisp (@strutvane/design-crisp)
Mail inbox http://localhost:8025
Admin admin@my-app.test
Password q7Vd-3kPz-Xm2c-8RtL (shown once; change it at first sign-in)
Every day: cd my-app; npm run dev
Commands: node strut list
Restyle: resources/ui/theme.css, or switch: node strut design:use vivid
Teammates: npm run setup (after git clone)

Then start the app:

Terminal window
cd my-app
npm run dev

Open http://localhost:3000 and sign in with the admin email and the password from the box. The API and the UI run together on one port and reload when you change a file.

Right after the project name, the installer asks how much you want to decide:

Something like this (the installer counts the quick questions it will really ask):

? How do you want to set up my-app?
❯ Recommended a few quick questions, sensible defaults for the rest
Custom Choose everything, grouped
Mode What you’re asked Flag
Recommended (default) The questions marked ★ below. In 0.2 that’s what you’re building, the design (full app only), how people sign in, teams (when people sign in), the database, and Docker. Everything else takes its default. --mode recommended
Custom Every question, grouped (App, Sign-in, Teams, Data, Infra, Features, Quality, Workflow, Security, AI, UI, Ops). --mode custom

Both lists grow release by release: a question that brings a package appears once that package ships. The AI coding assistants question (24), for example, joins Recommended mode in 0.3.

Some questions are asked in both modes whenever they apply, because they have no safe default: the connection details of your own database server, a password you chose to type, and the extra questions of a package you picked.

Nothing is final. Every optional feature can be added later with node strut install:<name>, which runs the same installer steps.

After the last question, you see every answer, the defaults included (something like this, shortened):

◇ Review ─────────────────────────────────────────────╮
│ Stack Full app: API + React UI │
│ Design crisp (@strutvane/design-crisp) │
│ Sign-in Email + password │
│ Security 2FA, email verification │
│ Teams no │
│ Database MySQL │
│ Docker With Docker │
│ Features Log viewer │
├─────────────────────────────────────────────────────╯
? What next?
❯ Create it
Change an answer
Cancel
  • Create it starts the setup.
  • Change an answer asks one question again. Answers that no longer apply are dropped (turn teams off, and the “how a request picks its team” answer goes away), and newly applying questions are asked.
  • Cancel stops before anything is written. The exit code is 130.

Your answers (never a secret) are saved in strutvane.json in the new project, which is committed. Later, node strut install:<name> reads it to know what you picked, and a teammate’s npm run setup rebuilds the project from it.

Questions marked ★ are asked in Recommended mode. Every question has a flag, so you can answer it on the command line instead. Bold is the default.

# Question Choices (default bold) Flag Brings
1 ★ Project name / folder the folder you typed --name my-app (or the first word: my-app)
2 ★ What are you building? Full app (API + admin UI), API only --stack full|api
3 ★ Which design should your app use? (full app only) Crisp, Vivid --design crisp|vivid @strutvane/design-crisp or @strutvane/design-vivid
4 Which React UI starter? (full app only) Admin screens from your models, blank React app --ui admin|blank @strutvane/ui

A design is a package that gives the screens their look: colours, fonts, the sidebar and top bar. Crisp is clean and business-first; Vivid is colourful with roomier cards. You can switch later with one command. See Designs.

# Question Choices (default bold) Flag Brings
5 ★ How do people sign in? Email and password, email link only (passwordless), no sign-in --auth email|magic-link|none @strutvane/auth
6 Extra sign-in security (pick several) two-factor, email verification, passkeys, public registration (off) --security 2fa,verification,passkeys,registration @strutvane/auth
7 Social login (pick several) none, Google, Microsoft, GitHub, Apple --social google,microsoft,github,apple @strutvane/social-login (0.3)
8 Enterprise SSO for your customers (SAML/OIDC + SCIM; needs teams) no, yes --sso @strutvane/sso (after 1.0)
9 API access for other apps personal access tokens, OAuth 2.1 server, none --api tokens|oauth|none @strutvane/auth, or @strutvane/oauth-server (after 1.0)
10 Starting roles admin + member, admin + manager + member + viewer --roles admin-member|admin-manager-member-viewer

What the three sign-in modes mean:

  • Email and password follows Laravel Fortify’s model. Password reset is always on, and the password tables are ordinary migrations in your app.
  • Email link only signs people in with a magic link: a link mailed to them that works once, for 15 minutes, and only in the browser that asked for it. Two-factor and passkeys still work on top.
  • No sign-in is for internal tools behind a company gateway. The generated API then requires an API token for every request, so nothing is open by default. The installer forces question 9 to tokens in this mode, and the Ready box tells you how to create one.

Public registration is off by default: only accounts you invite (or create) can sign in until you turn it on. That’s a security choice: an app that lets anyone register by accident is a common leak. See Authentication.

# Question Choices (default bold) Flag
11 ★ Teams / multi-tenancy (each customer company is a team) no, yes --teams
12 How a request picks its team team switcher in the app, subdomain (acme.yourapp.com) --tenant switcher|subdomain

Teams (also called multi-tenancy) means several customer companies share one app, and each sees only its own data. Saying yes to teams also makes question 8 (SSO) apply, and pre-selects PostgreSQL in question 13. See Tenancy.

# Question Choices (default bold) Flag
13 ★ Which database? MySQL (MariaDB is detected automatically), PostgreSQL (pre-selected with teams), SQLite `–db mysql
14 ★ Set up with Docker or without Docker? With Docker when Docker is installed and running, otherwise without (your own server). Docker is never required. --docker / --no-docker
15 ★ Your own server’s details (without Docker, MySQL, MariaDB or PostgreSQL) host 127.0.0.1, port 3306 (MySQL, MariaDB) or 5432 (PostgreSQL), database name, user root or postgres, then the password, masked; or one connection URL --db-host, --db-port, --db-name, --db-user; password: STRUT_DB_PASSWORD
16 First admin account email admin@<name>.test; password generated and shown once, or typed (masked) --admin-email, `–admin-password generate
17 Sample data, so the screens aren’t empty yes for the admin starter, no --sample-data

Question 15 is asked whenever it applies, in Recommended mode too, because your server’s details have no safe default.

About the database:

  • MySQL is the default. MariaDB (MySQL’s close cousin, shipped by XAMPP and many Linux systems) works the same way: the installer recognises it from the server’s version and writes DB_CONNECTION=mariadb. PostgreSQL adds row-level security: the database itself refuses to return another team’s rows, a second lock on top of the ORM’s tenant scope. SQLite is a single file and needs nothing installed.

  • With teams on MySQL, MariaDB or SQLite, the installer says so right away:

    Teams on MySQL: each team's data is isolated by the ORM tenant scope. PostgreSQL adds row-level security as a second lock.
  • A separate test database is created next to your development one, so npm test never touches your local data.

  • With PostgreSQL, the app connects as a plain database role, and migrations run as the owner role. That’s what makes row-level security really apply.

About Docker (question 14):

  • Docker is never required. Any database server works, with or without Docker, as in Laravel.
  • With Docker, everything runs in containers, like Laravel Sail: the app (Node 24), the database (MySQL 8.4 or PostgreSQL) and Mailpit, a fake mail inbox where you can read every email your app sends. Every node strut command you type is forwarded into the app container. See Docker.
  • Without Docker, the app runs on your computer. SQLite needs nothing; for MySQL, MariaDB or PostgreSQL you use your own server (question 15). The walkthrough is in the next section.
  • The default follows your computer: “with Docker” is pre-selected only when Docker is installed and running; otherwise “without Docker” is.

Without Docker: use XAMPP or your own MySQL

Section titled “Without Docker: use XAMPP or your own MySQL”

This is the path for XAMPP, WAMP, MAMP, Laragon, Postgres.app, a database installed the normal way, or a remote or cloud database. You need the server running before you start.

  1. Start your database server. In XAMPP, open the Control Panel and press Start next to MySQL. (Laragon: Start All. MAMP: Start Servers.)

  2. Create the app without Docker:

    Terminal window
    npm create strutvane@latest my-app -- --no-docker
  3. Answer question 15. Press Enter to keep each default that fits a local server. XAMPP’s MySQL user root has no password out of the box: leave the password empty and the installer accepts it, with a warning.

What you’ll see (something like this; the exact wording isn’t final):

◇ Which database?
│ MySQL
◇ Set up with Docker or without Docker?
│ Without Docker (the app runs on this computer)
◇ Database host (your server)
│ 127.0.0.1
◇ Database port
│ 3306
◇ Database name
│ my_app
◇ Database user
│ root
◇ Database password (saved only in .env)
│
▲ The password is empty. That's fine for XAMPP on your own computer, never for a shared or remote server.
◇ Connected: MariaDB 11.4 at 127.0.0.1:3306 (written as DB_CONNECTION=mariadb).
◇ Database my_app doesn't exist yet: created it (and my_app_test for tests).

If the installer can’t connect, it says why in plain words and lets you correct the details:

What you see What it means What to do
MySQL isn’t running: start it in the XAMPP control panel Nothing answers on that host and port Start the server, then choose Retry
Access denied for user root Wrong user or password Check the password (XAMPP’s root has none by default)
Unknown host The host name doesn’t resolve Use 127.0.0.1 for a server on this computer
Wrong port: MAMP uses 8889 Something else answers on that port, or nothing does Use your server’s port (MAMP’s MySQL: 8889)

If your user may not create databases (common on shared hosting and in the cloud), the installer prints the one SQL line to run yourself, for example:

CREATE DATABASE my_app CHARACTER SET utf8mb4;

A remote or cloud database: give the whole connection as one DB_URL instead of the separate details, and turn on TLS with DB_SSLMODE (and DB_SSL_CA for the provider’s certificate). A Unix socket goes in DB_SOCKET. These keys go into .env; see Configuration for every database key.

PostgreSQL on your own server: row-level security needs an app role that isn’t a superuser and can’t bypass row security. If your account may create roles, the installer creates my_app_owner and my_app_app for you. Otherwise it prints the SQL to run, and warns that connecting as a superuser (such as postgres) turns row-level security off. node strut security:check keeps repeating that warning until it’s fixed.

About the first admin (question 16): the generated password is shown once, in a real terminal only, and never written to any file: not .env, not .env.example, not strutvane.json. The admin must change it at first sign-in. Lost it? Set a new one:

Terminal window
node strut user:password admin@my-app.test
# Question Choices (default bold) Flag Brings
18 Cache, queue and sessions database (no extra service), Redis --cache-store database|redis @strutvane/redis (0.3)
19 File storage local disk, S3-compatible --storage local|s3 @strutvane/files (before 1.0)
20 Production mailer (development always uses the inbox) decide later, SMTP, Resend, Postmark, Amazon SES --mailer later|smtp|resend|postmark|ses Resend, Postmark and SES drivers (0.3)
21 Language, time zone, currency en, this computer’s time zone, USD --locale en, --timezone Europe/Berlin, --currency USD
# Question Default Flags
22 Extra features (pick several; popular first, type to search) log viewer --features log-viewer,billing or --features none; --feature-option <id>.<question>=<value>

There will be more than 100 packages, so this question never shows one long list. It shows:

  1. a short popular list, grouped: Operations (log viewer, queue dashboard, inspector, health), Data (charts and dashboards, search, import/export, API explorer), Back office (activity log, settings, media library, PDF, privacy, backups), Integrations (feature flags, webhooks, GraphQL, realtime, notification channels), Money (billing, invoicing), AI (AI SDK, MCP server);
  2. then “Search the full catalogue for more?”, where you type to search everything else.

The list comes from the published catalogue index, so it only offers packages that are published and work with the framework version you’re installing.

Some packages ask their own follow-up questions. Billing asks “Stripe or Paddle?”, for example. They’re written as data, not code, so nothing from a package runs before you’ve installed it. On the command line, answer them with --feature-option:

Terminal window
npm create strutvane@latest acme -- --features billing --feature-option billing.provider=paddle --yes

See Package Catalogue for how the catalogue works.

# Question Choices (default bold) Flag Brings
23 Tests Vitest, Vitest + Playwright browser tests, none --testing vitest|vitest-playwright|none @strutvane/browser-testing for Playwright (after 1.0)
24 ★ AI coding assistants (AGENTS.md, skills, local docs MCP) yes, no --agents / --no-agents @strutvane/agent-tools (0.3)
25 Git: a first commit, plus a GitHub Actions CI workflow git yes, CI yes --git / --no-git, --ci / --no-ci
36 Editor setup (VS Code settings, recommended extensions, format on save); optional dev container yes; dev container no --editor, --dev-container

The tests the installer generates use Vitest, the same runner your own tests use. In 0.2, Vitest is the only test runner offered: the Playwright browser-testing choice appears once @strutvane/browser-testing ships.

Question 24 writes an AGENTS.md file: instructions that AI coding assistants read before they change your code, plus skills and a local docs server for assistants.

A dev container is a committed .devcontainer/ folder that GitHub Codespaces and VS Code Dev Containers use to open your project in a ready-made container. See Docker.

# Question Choices (default bold) Flag Brings
26 Security profile Standard; Strict (2FA required for admins, breached-password check, 8-hour sessions, strict CSP, HSTS preload) --security-profile standard|strict
27 Record who changed what (activity history) yes for teams apps, no --activity-log @strutvane/activity-log (after 1.0)
28 AI features inside your app no; yes, then a provider: Anthropic, OpenAI, Google, local (Ollama) --ai, --ai-provider anthropic|openai|google|ollama @strutvane/ai (after 1.0)
29 Let AI agents use your app safely (MCP server) no, yes --mcp-server @strutvane/mcp-server (after 1.0)
30 Languages for the UI (pick several) English; add any --ui-languages en,de,pt-BR
31 Default appearance follow the system, light, dark --appearance system|light|dark
32 Installable app (PWA: home-screen icon, offline page) no, yes --pwa @strutvane/ui
33 Live updates (tables refresh when others change data) no, yes --live-updates @strutvane/realtime (after 1.0)
34 Monitoring none; OpenTelemetry export plus a health page --monitoring none|otel @strutvane/observability, @strutvane/health (before 1.0)
35 Where will you deploy? decide later; any Node host (VPS, Railway, Render); Docker image (Kubernetes, Fly, Cloud Run, ECS) --deploy later|node|docker
37 Start the dev server and open the browser now? (asked after setup) yes, no --dev / --no-dev

A few notes:

  • AI keys are never asked. Choosing a provider writes an empty key line into .env (ANTHROPIC_API_KEY=, for example). You paste the key there yourself later, so it never lands in your shell history or a CI log.
  • Deploy target writes a deploy recipe (deploy/README.md). “Docker image” also writes a committed, secure Dockerfile and .dockerignore. See Docker and Deployment.
  • Every app has the public /up health route, whatever you answer: it answers 200 {"status":"ok"} to GET and HEAD, and stays reachable during maintenance mode, so your host’s health check keeps working.

Every question has a flag. Any question you don’t answer with a flag is asked; with --yes, it takes its default.

Group Flags (default)
Setup --mode recommended|custom (recommended) · --yes
App --stack full|api (full) · --design crisp|vivid (crisp) · --ui admin|blank (admin)
Sign-in --auth email|magic-link|none (email) · --security 2fa,verification,passkeys,registration (2fa,verification) · --social google,microsoft,github,apple (none) · --sso (no) · --api tokens|oauth|none (tokens) · --roles admin-member|admin-manager-member-viewer (admin-member)
Teams --teams (no) · --tenant switcher|subdomain (switcher)
Data --db mysql|postgres|sqlite (mysql; postgres with teams) · --docker / --no-docker (Docker for MySQL and PostgreSQL) · --db-host · --db-port · --db-name · --db-user · --admin-email (admin@<name>.test) · --admin-password generate|type (generate) · --sample-data (yes for the admin starter)
Infra --cache-store database|redis (database) · --storage local|s3 (local) · --mailer later|smtp|resend|postmark|ses (later) · --locale (en) · --timezone (this computer’s) · --currency (USD)
Features --features <ids>|none (log-viewer) · --feature-option <id>.<question>=<value>
Quality and workflow --testing vitest|vitest-playwright|none (vitest) · --agents (yes) · --git (yes) · --ci (yes) · --editor (yes) · --dev-container (no)
Security, AI, UI, Ops --security-profile standard|strict (standard) · --activity-log (yes with teams) · --ai (no) · --ai-provider anthropic|openai|google|ollama · --mcp-server (no) · --ui-languages en,... (en) · --appearance system|light|dark (system) · --pwa (no) · --live-updates (no) · --monitoring none|otel (none) · --deploy later|node|docker (later)

Yes/no flags also have a --no- form: --no-git, --no-docker, --no-agents.

Secrets are never flags. A flag ends up in your shell history and in CI logs. Two secrets can be given through environment variables instead:

Variable Used for
STRUT_DB_PASSWORD Your own database server’s password (question 15), in CI
STRUT_ADMIN_PASSWORD A typed admin password (question 16, at least 12 characters), in CI

Unknown values are refused with the valid ones listed, and choices that don’t fit together are reported all at once (for example --design with --stack api, or --sso without --teams).

--yes accepts every default. The installer also takes the defaults by itself when it runs in CI (the CI environment variable is set) or when there’s no terminal to ask in.

Terminal window
npm create strutvane@latest my-app -- --yes

What you’ll see: the same app as pressing Enter everywhere: full app, Crisp, email and password with 2FA and verification, MySQL with Docker, the log viewer. The admin password isn’t shown (logs are kept and shared); set one with node strut user:password.

Terminal window
npm create strutvane@latest my-app -- --db sqlite --yes

What you’ll see: the default app on SQLite, with no Docker and nothing to install.

Terminal window
npm create strutvane@latest acme -- --stack full --design vivid --auth magic-link --security passkeys \
--teams --tenant subdomain --db postgres --docker --features log-viewer \
--security-profile strict --deploy docker --dev-container --yes

What you’ll see: no questions; a PostgreSQL teams app with the Vivid design, passwordless sign-in with passkeys, the strict security profile, the log viewer, a committed Dockerfile and a .devcontainer/. (Feature packages such as billing are added the same way, with --features and --feature-option, once they’re published.)

The Ready box always ends with the one command that recreates your project without questions: one flag per answer, built from your choices. Keep it for CI, or to create the same app again:

The same project without questions:
npm create strutvane@latest my-app -- --stack full --design crisp --ui admin --auth email --security 2fa,verification --api tokens --roles admin-member --no-teams --db mysql --docker --features log-viewer --testing vitest --git --ci --yes

(Shortened here; the real line has a flag for every question that applied.)

With npm create, options before -- belong to npm, not to the installer. npm keeps them for itself and never passes them on. The installer notices and stops with the corrected command:

npm kept these options for itself, so the installer never received them: --db sqlite
With npm create, options go after "--". Run this instead:
npm create strutvane@latest my-app -- --db sqlite
Or without the "--" rule: npx create-strutvane@latest my-app --db sqlite

The installer does everything, with one progress line per step. Progress is saved after every step in .strutvane/local/setup.json (git-ignored), so a failure never means starting over.

  1. Writes your project. All or nothing: if the folder exists and isn’t empty, nothing is written at all.
  2. Generates secrets into .env: APP_KEY (the root secret every other key is derived from) and the database passwords. They never go into .env.example, which is the file you commit.
  3. Checks ports. If 3000, 3306 or 8025 is taken, it picks the next free one and writes it into .env.
  4. Starts the database. With Docker: docker compose up -d --wait, which waits until the containers are healthy. Without Docker: creates the SQLite file, or checks that your own server answers.
  5. Installs dependencies with npm ci --ignore-scripts from a lockfile shipped with the starter (with Docker, inside the app container). Install scripts of dependencies don’t run unless they’re on an allowlist in package.json, which blocks a common way malware spreads through npm.
  6. Migrates and seeds (node strut migrate --seed): creates your tables, your roles and the first admin user.
  7. Creates a git repository with a first commit, but only after checking that .env, .strutvane/local/, docker/, SQLite files and storage/ are git-ignored and not staged.
  8. Offers to start the app (question 37).

What you’ll see (with Docker, --yes; a real terminal also shows spinners):

Strutvane: new project
✔ Files written (33 files in C:\Users\you\projects\acme-portal) 41ms
✔ Secrets generated in .env (APP_KEY, DB_PASSWORD, DB_ROOT_PASSWORD) 1ms
✔ Ports checked (3000 free; 3306 free; 8025 free) 15ms
✔ Containers running and healthy (app, db, mailpit) 15.3s
✔ Dependencies installed with npm (added 13 packages) 4.8s
✔ Migrations run (3 new, 3 total); Admin created: admin@acme-portal.test; Database seeded 850ms
✔ Git repository created (main, 1 commit) 1.9s
── Ready ───────────────────────────────────────────────────────
App http://localhost:3000
Database MySQL in Docker, 127.0.0.1:3306/acme_portal
Design crisp (@strutvane/design-crisp)
Mail inbox http://localhost:8025
Admin admin@acme-portal.test
Password not shown here. Set one with: node strut user:password admin@acme-portal.test
Every day: cd acme-portal; npm run dev
Commands: node strut list
Restyle: resources/ui/theme.css, or switch: node strut design:use vivid
Teammates: npm run setup (after git clone)

This is from the prototype, so file and package counts are smaller than in a real app. The Ready box changes with your answers: no Mail inbox line without Docker, a “signs in with an emailed link” note for email-link sign-in, and an “every request needs an API token” line with no sign-in.

The main files the installer writes (the exact list depends on your answers):

Path What it is
package.json, package-lock.json, .npmrc Dependencies, the shipped lockfile, and ignore-scripts=true
strut.js node strut <command>, your project’s command line
strutvane.json Your installer answers (never a secret); committed, so npm run setup can rebuild a fresh clone from it
.strutvane/ Generated types, resources and the API client; committed
.env, .env.example Your settings: .env holds this machine’s values and secrets (git-ignored); .env.example lists every key, without secrets (committed). See Configuration
app/, bootstrap/, config/, routes/, database/, resources/ui/, tests/ The app itself. See Directory Structure
config/ui.ts, resources/ui/theme.css Which design you use, and your own overrides
.github/workflows/ci.yml The CI workflow (question 25)
.vscode/ Editor settings (question 36)
AGENTS.md Instructions for AI coding assistants (question 24, from 0.3)
deploy/README.md A deploy recipe (question 35)
Dockerfile, .dockerignore, .devcontainer/ Only if you picked them (questions 35 and 36); committed
docker/compose.yaml The local Docker setup (Docker mode only); git-ignored
.strutvane/local/setup.json Setup progress on this computer, for npm run setup; git-ignored, like everything in .strutvane/local/

The scripts in package.json:

Script Runs What it’s for
npm run dev node strut dev Every day: API and UI on one port, with hot reload
npm run setup node strut setup Finish setup, or set up a fresh clone
npm test node strut test Your tests
npm run build node strut build A production build
npm start node build/server.js Run the production build

The installer recovers instead of leaving half a project. When a step fails, it says what happened and offers choices:

What failed What you can choose
Docker isn’t installed or isn’t running Use my own database server (XAMPP, a local install or a remote server; asks question 15), Start Docker (then retry), Continue without Docker (SQLite), Retry
Your own server can’t be reached or refuses the login The reason in plain words (see the table in “Without Docker” above); correct the details, then Retry
A port is busy Nothing to do: the next free port is written to .env (and retried once if it’s taken at start-up)
npm ci hits a network error or a Windows file lock One automatic retry; then Retry, Skip for now, Stop here
npm ci fails another way (for example a registry 401) The last 20 lines, the log file’s path and a hint; then Retry, Skip for now, Stop here
Your own database server doesn’t answer The message names host:port; Retry or Skip (migrations wait)
Migrations can’t reach the database “database unreachable” with the fix; Retry or Skip
No git identity, or git isn’t installed The two git config commands to run, or an install hint
A secret file isn’t git-ignored or was staged No commit is made, and everything is unstaged

Use my own database server asks for your server’s details and rewrites the database settings in .env. Continue without Docker (SQLite) switches .env to SQLite and keeps everything else, so the app starts right away. (The prototype offers SQLite, Skip and Stop here; the own-server choice and this order are designed, not built yet.) In CI there’s nobody to ask, so the run stops at the first failure.

Skip for now or Stop here keeps the project. The last screen lists what’s left:

The project is in C:\Users\you\projects\my-app, but these steps are not done: database, migrate.
Progress is saved in .strutvane\local\setup.json. Fix the cause shown above, then run:
cd my-app; npm run setup
Setup continues from the first unfinished step.
Terminal window
cd my-app
npm run setup

What you’ll see: steps that are already done are skipped, and setup continues from the first unfinished one. It re-checks the secrets in .env instead of trusting the saved progress, so a placeholder like APP_KEY=changeme is replaced.

A password you typed in question 16 lives only in memory, so a resumed setup generates a new admin password instead and shows it once.

Code Meaning
0 Created and fully set up.
1 Nothing was created (for example an invalid name, a folder that isn’t empty, or choices that don’t fit together).
2 The project was created, but setup didn’t finish. Run npm run setup.
130 You cancelled.
Terminal window
npm create strutvane@latest my-app -- --yes || echo "installer exit code: $?"

Both work, and the commands you type are the same. Docker is never required.

With Docker Without Docker
What runs where The app, the database and Mailpit run in containers, like Laravel Sail. The app runs on your computer with Node.js.
What you install Node.js (the node strut forwarder needs it on your computer; nothing else does) and Docker Desktop. Node.js, plus your own MySQL, MariaDB or PostgreSQL server (XAMPP, WAMP, MAMP, Laragon, Postgres.app, a normal install, or a remote one), or nothing with SQLite.
node strut … and npm run dev Forwarded into the app container for you. Run on your computer.
Mail Every email lands in Mailpit at http://localhost:8025. Emails are written to the log.
Best for Teams who want identical versions everywhere. Anyone who already runs a database server, quick experiments, or machines where Docker isn’t allowed.

The local Docker files live in docker/compose.yaml. They’re for local development only, so they’re git-ignored. A production Dockerfile and a dev container are separate, opt-in choices (questions 35 and 36) and are committed. The Docker page explains it all: services, ports, node strut services:up, the shell, npm, npx and node pass-throughs, and Windows/WSL notes.

  • Node.js: use the installer from nodejs.org or a version manager. Check with node --version.

  • Linux and Docker: if Docker says permission denied on docker.sock, add yourself to the docker group, then log out and back in:

    Terminal window
    sudo usermod -aG docker $USER

    The installer shows this command and offers Retry or SQLite meanwhile.

  • File ownership in Docker (Linux): the app container runs as your user id (STRUT_UID/STRUT_GID in .env), so files it writes belong to you, not to root.

  • Use PowerShell or Windows Terminal. Every command in these docs works there as written, and node strut needs no wrapper or execution-policy change.
  • Scripts disabled? Type npm.cmd instead of npm, or run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once.
  • Docker Desktop must be running before the containers can start. Use the WSL2 backend; it’s also faster at noticing file changes.
  • Antivirus or an open editor can lock files for a moment during npm ci. The installer retries once after 2 seconds; if it still fails, close the editor and run npm run setup.
  • Project names that Windows refuses as file names (con, nul, aux) are rejected before anything is written.
npm kept these options for itself, so the installer never received them: --db sqlite
With npm create, options go after "--". Run this instead:

Why: without --, npm keeps --db for itself and never passes it on.

Fix: put the installer’s options after --, or use npx, which has no such rule:

Terminal window
npm create strutvane@latest my-app -- --db sqlite
npx create-strutvane@latest my-app --db sqlite
C:\Users\you\projects\my-app already exists and is not empty. Choose another name (nothing is ever overwritten).

Why: the installer never overwrites files.

Fix: pick another name, or move the old folder away:

Terminal window
npm create strutvane@latest my-app-2
Docker is installed but not running.
Start Docker Desktop, wait until it says "running", then choose Retry.

Why: the Docker command exists, but the Docker engine isn’t started.

Fix: choose Use my own database server if XAMPP or another MySQL is running, or start Docker Desktop and choose Retry, or choose Continue without Docker (SQLite). If you already stopped, continue later:

Terminal window
cd my-app
npm run setup
Docker is not installed (the docker command was not found).
Install Docker Desktop (https://docs.docker.com/get-docker/; on Windows use the WSL2 backend), or continue without Docker on SQLite.

Why: you asked for Docker (--docker), but there’s no Docker on this computer.

Fix: choose Use my own database server or Continue without Docker (SQLite), or create the project without Docker from the start:

Terminal window
npm create strutvane@latest my-app -- --no-docker --db sqlite

Why: it’s shown once, in a real terminal only, and never saved to a file. With --yes or in CI it isn’t shown at all, because logs are kept and shared.

Fix: set a new one:

Terminal window
node strut user:password admin@my-app.test

Why: the project was created, but a setup step (often starting the database) didn’t finish.

Fix: read the last lines it printed, fix the cause (often: start Docker Desktop), then continue:

Terminal window
cd my-app
npm run setup

PowerShell says running scripts is disabled

Section titled “PowerShell says running scripts is disabled”
npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system.

Why: Windows’ execution policy blocks npm’s PowerShell wrapper.

Fix: use npm.cmd, or allow signed scripts for your user once:

Terminal window
npm.cmd create strutvane@latest my-app
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Why: Strutvane needs Node.js 24.3 or newer; earlier versions break arguments in PowerShell and lack features it relies on.

Fix: install the current LTS from nodejs.org, open a new terminal and check:

Terminal window
node --version