Configuration
Settings are the values your app needs that aren’t code: its name, its address, how to reach the database, secret keys. This page shows where they live, how to read them from your code, what happens when one is wrong, and every key a new app’s .env contains.
Two places for settings
Section titled “Two places for settings”A Strutvane app keeps its settings in two places:
| Where | What goes there | Committed to git? |
|---|---|---|
.env |
Values that change from machine to machine: passwords, keys, ports, the database name. | Never |
config/*.ts |
Everything else, plus which .env values to read, with their types and defaults. |
Yes |
So config/database.ts says “the database port is a number, read from DB_PORT, default 3306”, and .env on your laptop says DB_PORT=3307.
The .env file
Section titled “The .env file”.env sits in your project’s root folder. Each line is a KEY=value pair. Here is the start of a new app’s .env (MySQL, without Docker; the secret values are replaced by placeholders here):
# ApplicationAPP_NAME=my-appAPP_ENV=localAPP_KEY=generated-for-youAPP_DEBUG=trueAPP_URL=http://localhost:3000APP_PORT=3000
# DatabaseDB_CONNECTION=mysqlDB_HOST=127.0.0.1DB_PORT=3306DB_DATABASE=my_appDB_TEST_DATABASE=my_app_testDB_USERNAME=my_appDB_PASSWORD=the-password-you-typedYou don’t write this file by hand. npm create strutvane@latest writes it, generates the secrets (like APP_KEY) and picks free ports. The full list of keys is in Every .env key below.
.env.example: the list of every setting
Section titled “.env.example: the list of every setting”Next to .env is .env.example. It has the same keys, with every secret left empty, and it is committed. It’s how a teammate (or a server) knows which settings exist. A few values also differ on purpose: .env.example says APP_ENV=production and APP_DEBUG=false, so a server that copies it starts safe.
After git clone, a teammate runs npm run setup, which creates .env and fills in fresh secrets.
Real environment variables win
Section titled “Real environment variables win”On servers you often set variables in the environment instead of a file (in your hosting dashboard, Docker or CI). When a key is set both in the environment and in .env, the environment wins. That’s Laravel’s rule too, and it means one build works everywhere.
Config files
Section titled “Config files”Each file in config/ returns one group of settings: config/app.ts, config/database.ts, config/auth.ts, config/logging.ts and so on. A config file reads .env through a small, typed reader (env), so every value comes out with the right type.
The smallest config file
Section titled “The smallest config file”import { defineConfig } from '@strutvane/framework'
export default defineConfig((env) => ({ name: env.string('APP_NAME', 'My App'),}))What you’ll see: config('app.name') returns 'My App', or whatever APP_NAME says in .env.
A typical config file
Section titled “A typical config file”import { defineConfig } from '@strutvane/framework'
export default defineConfig((env) => ({ name: env.string('APP_NAME', 'My App'), env: env.oneOf('APP_ENV', ['local', 'testing', 'staging', 'production'], 'production'), debug: env.boolean('APP_DEBUG', false), url: env.url('APP_URL', 'http://localhost:3000'), key: env.string('APP_KEY'), // no default: the app refuses to start without it}))Every config file is listed in config/index.ts, so the types (and node strut about) know about it:
import app from './app.ts'import database from './database.ts'
export const config = { app, database }Every reader
Section titled “Every reader”| Reader | Returns | Without a default… | Example |
|---|---|---|---|
env.string(key, default?) |
text | the key is required | env.string('APP_NAME', 'My App') |
env.optional(key) |
text or undefined |
it’s undefined |
env.optional('DB_PASSWORD') |
env.integer(key, default?) |
a whole number | required | env.integer('DB_PORT', 3306) |
env.boolean(key, default?) |
true/false (also accepts 1/0) |
required | env.boolean('APP_DEBUG', false) |
env.oneOf(key, list, default?) |
one value from the list, typed as that list | required | env.oneOf('APP_ENV', ['local', 'production']) |
env.url(key, default?) |
an absolute http(s) URL |
required | env.url('APP_URL') |
An empty value (APP_NAME=) counts as “not set”, as in Laravel.
Reading a setting anywhere
Section titled “Reading a setting anywhere”import { config } from '@strutvane/framework'
const title = config('app.name') // stringconst debug = config('app.debug') // booleanWhat you’ll see: the values from your config files, already typed. A typo like config('app.debg') is a compile error, not a silent undefined. See Helpers for how config() finds the current app.
An advanced config file: one setting, several connections
Section titled “An advanced config file: one setting, several connections”import { defineConfig } from '@strutvane/framework'
export default defineConfig((env) => ({ default: env.oneOf('DB_CONNECTION', ['mysql', 'mariadb', 'pgsql', 'sqlite'], 'mysql'), connections: { mysql: { driver: 'mysql', host: env.string('DB_HOST', '127.0.0.1'), port: env.integer('DB_PORT', 3306), database: env.string('DB_DATABASE', 'my_app'), username: env.string('DB_USERNAME', 'root'), password: env.optional('DB_PASSWORD'), }, sqlite: { driver: 'sqlite', database: env.string('DB_DATABASE', 'database/database.sqlite'), }, },}))What you’ll see: config('database.default') is typed as 'mysql' | 'mariadb' | 'pgsql' | 'sqlite', and config('database.connections.mysql.port') is a number.
Every mistake, reported at once
Section titled “Every mistake, reported at once”When the app starts (and when any node strut command runs), Strutvane checks every setting before doing anything else. If something is wrong, it stops and lists all the problems together:
✖ The app can't start: 2 environment variables need attention. - APP_KEY is required (a text value); add it to .env (read in config/app.ts) - APP_DEBUG must be true or false (got "yes") (read in config/app.ts) → Fix the values in .env (see .env.example for every key) and start again.Why all at once? Fixing a new server one setting at a time (“restart, next error, restart…”) is the most frustrating loop in operations.
Every .env key
Section titled “Every .env key”The installer writes only the keys your answers need, in this order. “Written today” means the installer prototype (spike 13) already writes the key; everything else is designed and marked.
Application
Section titled “Application”| Key | What it’s for | Default in a new app |
|---|---|---|
APP_NAME |
Your app’s name, shown in the UI and in emails. | the project name |
APP_ENV |
local, testing, staging or production. In production, seeders don’t run by themselves, and node strut migrate asks for confirmation unless you pass --force (as in Laravel). The debug error page only appears in local and testing. |
local (.env.example: production) |
APP_KEY |
The root secret: it signs cookies and CSRF tokens and encrypts data, and every other key is derived from it. 32 random bytes, generated. Keep it secret. | generated |
APP_DEBUG |
true shows detailed error pages, in local/testing only. With APP_ENV=production, APP_DEBUG=true stops the app from starting unless you pass --force-debug, and even then the debug page stays off. |
true (.env.example: false) |
APP_URL |
The address people use to reach the app. Also the origin the CSRF check trusts. | http://localhost:3000 |
APP_PORT |
The port npm run dev listens on. The installer picks the next free one if 3000 is taken. |
3000 |
APP_PREVIOUS_KEYS |
Old keys kept by node strut key:rotate, so existing cookies and encrypted values still open. Designed. |
not set |
Database
Section titled “Database”| Key | What it’s for | Default in a new app |
|---|---|---|
DB_CONNECTION |
mysql, mariadb, pgsql or sqlite. postgres is accepted as another name for pgsql. The installer writes mariadb when it finds a MariaDB server (XAMPP ships one). |
mysql |
DB_HOST, DB_PORT |
Where the database server is. With Docker, DB_HOST=db (the container’s name) and the database’s own port. |
127.0.0.1 / 3306 (PostgreSQL 5432; Docker: db) |
DB_DATABASE |
The database name, or the file for SQLite. | your project name (SQLite: database/database.sqlite) |
DB_TEST_DATABASE |
A separate database for npm test, so tests never touch your local data. |
<name>_test (SQLite: database/testing.sqlite) |
DB_USERNAME, DB_PASSWORD |
How the app signs in to the database. With Docker the password is generated; with your own server it’s the one you typed. An empty password is accepted for a server on your own computer (XAMPP’s root), with a warning. |
root (PostgreSQL postgres); Docker: your project name |
DB_URL |
The whole connection in one line, as cloud providers give it: mysql://user:password@host:3306/my_app. When it’s set, it wins over the separate keys above. A secret, because it contains the password. |
not set |
DB_SOCKET |
A Unix socket instead of host and port (MySQL, MariaDB or PostgreSQL on macOS and Linux). | not set |
DB_SSLMODE |
Encrypt the connection: disable, prefer, require, verify-ca or verify-full (PostgreSQL’s names, as in Laravel). Use require or stricter for a remote or cloud database. |
not set (no TLS for a local server) |
DB_SSL_CA |
The path to your provider’s CA certificate, for verify-ca and verify-full. |
not set |
DB_MIGRATION_USERNAME, DB_MIGRATION_PASSWORD |
PostgreSQL. Migrations run as an “owner” role, while the app connects as a plain role that can’t bypass row-level security. With Docker the installer creates both roles; on your own server it creates them when your account may, or prints the SQL. Password generated in Docker. | <name>_owner |
DB_ROOT_PASSWORD |
Docker only. The database image needs an administrator password; the app never uses it. Generated. | generated |
DB_CONNECTION=pgsqlDB_URL=postgres://my_app_app:the-password@db.example.com:5432/my_appDB_SSLMODE=verify-fullDB_SSL_CA=storage/certs/provider-ca.pem| Key | What it’s for | Default in a new app |
|---|---|---|
MAIL_MAILER |
How mail is sent. Without Docker, log writes mail to the log. With Docker, smtp sends it to Mailpit, a local inbox. |
log (Docker: smtp) |
MAIL_HOST, MAIL_PORT |
Docker only. Mailpit inside Docker. | mailpit / 1025 |
FORWARD_MAILPIT_PORT |
Docker only. The port of the Mailpit inbox on your computer. | 8025 |
Docker (local only)
Section titled “Docker (local only)”These exist only when you chose with Docker. See Docker.
| Key | What it’s for | Default in a new app |
|---|---|---|
COMPOSE_PROJECT_NAME |
Names your containers, so two projects never touch each other’s. | from the project name |
STRUT_UID, STRUT_GID |
The user the app container runs as on Linux, so files it writes belong to you, not to root. Docker Desktop on Windows and macOS maps ownership itself. |
1000 |
FORWARD_DB_PORT |
The database’s port on your computer, for a GUI client such as TablePlus. | 3306 or 5432 |
Which sign-in features are on lives in config/auth.ts, which the installer writes from your answers, not in .env keys. The only auth key in .env is the first admin’s address:
| Key | What it’s for | Default in a new app |
|---|---|---|
SEED_ADMIN_EMAIL |
The first admin’s email, used by the default seeder. | admin@<name>.test |
There is no SEED_ADMIN_PASSWORD. The first admin’s password is never written to any file: the installer shows a generated one once, or you type one. See Seeding. There is no AUTH_SECRET either: APP_KEY is the one root secret, and auth derives its own keys from it.
Teams and AI
Section titled “Teams and AI”| Key | What it’s for | Default in a new app |
|---|---|---|
TENANCY_ENABLED |
Prototype only. The installer prototype writes it when you chose teams. Decided instead: teams are switched on in config/tenancy.ts ({ enabled, column: 'tenant_id' }), where enabled is false unless you answered yes to teams; the ORM’s tenant scope is active only when it’s on. Coming in 0.2. |
true (prototype) |
AI_PROVIDER |
Written when you chose AI features: anthropic, openai, google or ollama. |
your choice |
ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY |
The provider’s key. Written empty: the installer never asks for it, so it can’t end up in your shell history or a CI log. Paste it in yourself. | empty |
OLLAMA_HOST |
For local models with Ollama. | http://127.0.0.1:11434 |
Logging
Section titled “Logging”| Key | What it’s for | Default |
|---|---|---|
LOG_CHANNEL |
Where logs go: single, daily, stack, stderr, stdout, slack, null, or a channel you define. |
stack (the production Dockerfile sets stderr) |
LOG_STACK |
The channels stack writes to, comma-separated (daily,slack). |
daily |
LOG_LEVEL |
The least important level that’s still written. | debug in local, info otherwise |
LOG_DAILY_DAYS |
How many days of daily files to keep. | 14 |
LOG_FORMAT |
line (readable) or json (one JSON object per line). |
line (the production Dockerfile sets json) |
LOG_MAX_FILE_SIZE |
A file grows to this size, then a new part file starts. | 100mb |
LOG_PATH |
The folder for log files. | storage/logs |
LOG_SLACK_WEBHOOK_URL |
The Slack webhook for the slack channel. A secret. |
not set |
LOG_DEPRECATIONS_CHANNEL |
Where deprecation warnings go. | null (discarded) |
Which secrets are generated
Section titled “Which secrets are generated”APP_KEY, and with Docker DB_PASSWORD, DB_ROOT_PASSWORD and DB_MIGRATION_PASSWORD (PostgreSQL). Each is 32 random bytes, written to .env only, always empty in .env.example. If npm run setup finds a placeholder such as APP_KEY=changeme, it replaces it. On macOS and Linux, .env is created readable only by you.
With Docker or without Docker
Section titled “With Docker or without Docker”What .env looks like depends on that installer answer:
| With Docker | Without Docker | |
|---|---|---|
| Database host | DB_HOST=db (the container’s name; only the app container can reach it by that name) |
127.0.0.1 or your server, or a SQLite file |
| Database port on your computer | FORWARD_DB_PORT |
DB_PORT |
MAIL_MAILER=smtp to Mailpit; inbox at http://localhost:8025 |
MAIL_MAILER=log |
|
Who reads .env |
the app container (every node strut command runs there) |
Node on your computer |
You don’t edit the Docker values by hand: the installer writes the values that match the containers it starts. See Docker.
The files next to .env
Section titled “The files next to .env”strutvane.json(committed) records every installer answer, defaults included, plus the packages they brought, sonode strut install:<name>later knows what you picked. It never holds a secret.config/ui.ts(full-stack apps) names your design (design: 'crisp'), the default appearance, the UI languages and a few UI switches. See Designs..strutvane/(committed) holds generated types, resources and the API client..strutvane/local/setup.json(git-ignored, like everything in.strutvane/local/) tracks the installer’s steps on this computer, sonpm run setupcan skip what’s done. It’s optional: a fresh clone sets up fromstrutvane.jsonalone. It holds no secret either.
Setting a variable for one command
Section titled “Setting a variable for one command”Sometimes you want a different value only once, for example to see what production would do. The environment beats .env.
macOS / Linux (bash, zsh):
APP_ENV=production node strut aboutWindows PowerShell:
$env:APP_ENV='production'; node strut about; Remove-Item Env:APP_ENVWindows cmd:
set APP_ENV=production && node strut aboutCommitting an encrypted .env.production
Section titled “Committing an encrypted .env.production”Some teams want production settings in git, encrypted. Like Laravel’s env:encrypt:
node strut env:encrypt --env=production # writes .env.production.encryptednode strut env:decrypt --env=production # on the server, with the key in an environment variableSwitching database
Section titled “Switching database”To move from SQLite to MySQL later (or the other way around), change the DB_* keys in .env and run your migrations against the new database:
DB_CONNECTION=mysqlDB_HOST=127.0.0.1DB_PORT=3306DB_DATABASE=my_appDB_USERNAME=rootDB_PASSWORD=secretnode strut migrateYour migrations are written once and work on MySQL, PostgreSQL and SQLite. See Migrations.
Common mistakes
Section titled “Common mistakes”The app won’t start: “environment variables need attention”
Section titled “The app won’t start: “environment variables need attention”” ✖ The app can't start: 1 environment variable needs attention. - APP_KEY is required (a text value); add it to .env (read in config/app.ts)Why: .env is missing, or a required key is empty. This happens after git clone, because .env is never committed.
Fix: let setup create it with fresh secrets:
npm run setup“must be true or false (got “yes”)”
Section titled ““must be true or false (got “yes”)”” - APP_DEBUG must be true or false (got "yes") (read in config/app.ts)Why: boolean settings accept only true, false, 1 or 0.
Fix: APP_DEBUG=true in .env.
My change to .env didn’t do anything
Section titled “My change to .env didn’t do anything”Why: the same key is also set in your shell or by your host, and the real environment wins over .env.
Fix: check where it’s set (echo $APP_ENV in bash, $env:APP_ENV in PowerShell) and remove it there, or change it there.
I can’t find the admin password in .env
Section titled “I can’t find the admin password in .env”Why: it’s never stored in a file. The installer showed it once. Fix: set a new one:
node strut user:password admin@my-app.testMy database GUI can’t connect with DB_HOST=db
Section titled “My database GUI can’t connect with DB_HOST=db”Why: db is a name only the containers know. Your computer reaches the database through the forwarded port.
Fix: connect your GUI to 127.0.0.1 on the port in FORWARD_DB_PORT, with DB_USERNAME and DB_PASSWORD. Leave DB_HOST=db as it is.
config('app.nmae') doesn’t compile
Section titled “config('app.nmae') doesn’t compile”error TS2345: Argument of type '"app.nmae"' is not assignable to parameter of type …Why: config keys are typed from your config files, so typos are caught before the code runs.
Fix: use the right key (config('app.name')). If it’s a new setting, add it to the config file first.
Next steps
Section titled “Next steps”- Docker: what the Docker keys do.
- Logging: the
LOG_*keys in action. - Directory Structure: where
config/and everything else lives. - Helpers:
config(),route()and friends.