Skip to main content

⚙️ Configuration & Environment

NodeStack can be configured via environment variables, CLI flags, or programmatic options.


Environment Variables​

VariableDefaultDescription
NODESTACK_DATA_DIR./nodestack_dataDirectory where SQLite database and uploaded files are stored.
NODESTACK_PORT8090HTTP port for the API server and Web Admin UI.
NODESTACK_HOST127.0.0.1Network interface to bind to (0.0.0.0 for all interfaces/containers).
NODESTACK_JWT_SECRETAuto-generatedSecret key used to sign and verify authentication tokens.
NODESTACK_APP_NAMENodeStackApplication name displayed in the Web Admin UI and OpenAPI docs.
NODESTACK_MAX_UPLOAD_SIZE52428800 (50MB)Maximum file size in bytes for multipart uploads.
NODESTACK_CORS_ORIGIN*Allowed CORS origins for browser clients.
NODESTACK_LOG_LEVELinfoLogging 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();