Files
DataStack/docs/reference/configuration-reference.md
T
Team Dark Devil 40a6855724 feat(sdk): refactor Python SDK documentation
- Standardize Python SDK (`datastack`) documentation with a new multi-file suite.
- Update `datastack-sdk` to serve as a backward-compatible shim for the canonical `datastack` package.
- Update project manifest and memory map to reflect current SDK structure and v2.2.0 features.
2026-11-18 10:03:40 +06:00

4.4 KiB
Raw Blame History

Complete Configuration Reference

This document provides the exhaustive specification for every environment variable, .env parameter, and runtime database setting supported by DataStack.


1. Environment Variables (.env)

Environment variables are loaded on container or process boot.

Variable Name Type Production Requirement Default Value (Dev) Description & Constraints
NODE_ENV String Required development Runtime mode. Must be set to production in live deployments to enforce fail-closed security and secure cookies.
DATASTACK_ADMIN_SESSION_SECRET String Required Fallback key Cryptographic secret for signing WebCrypto HMAC-SHA256 operator session cookies. Min length: 32 chars.
DATASTACK_JWT_SECRET String Required Fallback key Master HMAC-SHA256 secret used to sign and verify client SDK authentication tokens. Min length: 32 chars.
DATASTACK_ADMIN_SETUP_KEY String Required Fallback key One-time secret key required to access /vcon/setup and create the initial administrator account. Min length: 32 chars.
DATASTACK_INTERNAL_SECRET String Recommended SHA-256 of JWT secret Shared secret authorizing internal IPC between Port 3000 and Port 4000 via x-datastack-internal-secret. Min length: 32 chars.
DATASTACK_ADMIN_EMAIL String Optional admin@example.com Default admin contact email used during development or bootstrap.
DATASTACK_ALLOW_DEMO_ADMIN Boolean Strictly Forbidden in Prod false When true, displays demo credentials on login screen. Throws fatal error if enabled in production.
DATABASE_URL String Recommended undefined PostgreSQL connection string (postgresql://user:pass@host:5432/dbname). If omitted, in-memory mock mode is activated.
REDIS_URL String Optional undefined Redis connection URI (redis://host:6379). Enables multi-worker buffer queuing and distributed flush locks.
PORT Integer Optional 3000 Port for the Next.js 15 web application and REST API.
PORT_SOCKET Integer Optional 4000 Port for the Express 5 + Socket.IO ingestion service.
INGESTION_INTERNAL_URL String Optional http://127.0.0.1:4000 Base URL used by Port 3000 to send bridge notifications to Port 4000 (/internal/*).

2. Runtime Platform Settings (admin_settings Table)

Runtime settings are persisted in PostgreSQL (admin_settings row with id = 'default'), configurable via /vcon/settings, and synchronized instantly across processes.

Parameter Key Storage Column Type Default Range / Constraints Functional Impact
serverPort server_port Integer 4000 1024 – 65535 Ingestion service port reported across the cluster.
webPort web_port Integer 3000 1024 – 65535 Web dashboard port reported across the cluster.
maxEventsPerSec max_events_per_sec Integer 100 1 – 10,000 Global ingestion rate limit ceiling. Exceeding events receive HTTP 429 or socket error.
maxPayloadSizeKb max_payload_size_kb Integer 100 1 – 10,240 (10 MB) Maximum permitted size in KB for any single event. Larger payloads rejected with HTTP 413.
batchFlushThreshold batch_flush_threshold Integer 500 10 – 50,000 Buffer queue depth that triggers an immediate synchronous flush to disk.
batchFlushIntervalMs batch_flush_interval_ms Integer 2000 200 – 60,000 (60s) Maximum age in milliseconds before pending events in queue are written to disk.
fileRotationMb file_rotation_mb Integer 100 5 – 1,024 (1 GB) Partition size threshold on disk. When exceeded, output continues to {YYYY-MM-DD}-part2.csv.
enableIdempotency enable_idempotency Boolean true true / false Enables 5-minute sliding-window deduplication for events carrying an eventId.
autoPruneDays auto_prune_days Integer 30 0 – 3,650 Purges partition files older than this day threshold. Setting to 0 retains archives indefinitely.
jwtSecret jwt_secret String .env value Min 16 chars Master JWT signing secret. Rotating triggers automated re-signing of all client tokens.
updatedAt updated_at DateTime now() ISO 8601 string Timestamp recording the last administrative modification of platform settings.