⚙️ Configuration & Environment
NodeStack can be configured via environment variables, CLI flags, or programmatic options.
Environment Variables
| Variable | Default | Description |
|---|---|---|
NODESTACK_DATA_DIR | ./nodestack_data | Directory where SQLite database and uploaded files are stored. |
NODESTACK_PORT | 8090 | HTTP port for the API server and Web Admin UI. |
NODESTACK_HOST | 127.0.0.1 | Network interface to bind to (0.0.0.0 for all interfaces/containers). |
NODESTACK_JWT_SECRET | Auto-generated | Secret key used to sign and verify authentication tokens. |
NODESTACK_APP_NAME | NodeStack | Application name displayed in the Web Admin UI and OpenAPI docs. |
NODESTACK_MAX_UPLOAD_SIZE | 52428800 (50MB) | Maximum file size in bytes for multipart uploads. |
NODESTACK_CORS_ORIGIN | * | Allowed CORS origins for browser clients. |
NODESTACK_LOG_LEVEL | info | Logging verbosity (fatal, error, warn, info, debug, trace). |
CLI Flags
You can pass configuration flags directly when launching NodeStack:
# Launch on custom port and host
npx @nodestackapp/server start --port 3000 --host 0.0.0.0
# Specify a custom data directory
npx @nodestackapp/server start --dir /var/data/nodestack
# Enable debug logging
npx @nodestackapp/server start --log-level debug
Database Management CLI (nodestack db)
NodeStack includes built-in commands for managing database engines, performing connection diagnostics, and running live data migrations across SQLite, PostgreSQL, and MSSQL:
# Display active engine status, connection health, and latency
nodestack db status [--app <app-slug>]
# Test connection to a PostgreSQL or MSSQL target
nodestack db test postgres "postgres://user:pass@localhost:5432/nodestack?ssl=true"
nodestack db test mssql --host localhost --port 1433 --user sa --password secret --database myapp
# Save configuration without migrating immediately
nodestack db configure postgres "postgres://user:pass@localhost:5432/nodestack"
# Live migration and engine cutover
nodestack db switch postgres "postgres://user:pass@localhost:5432/nodestack" --migrate --confirm migrate
Programmatic Configuration
When using NodeStack as a library in TypeScript:
import { NodeStack } from '@nodestackapp/server';
const app = new NodeStack({
dataDir: './my_app_data',
port: 8090,
host: '0.0.0.0',
jwtSecret: process.env.JWT_SECRET || 'super-secret-key-32-chars-min',
appName: 'My Custom App',
cors: {
origin: ['https://myapp.com', 'http://localhost:3000'],
credentials: true,
},
});
await app.start();