Configuration

MooseStack settings live in two places: a project config file and runtime environment variables. The config file is tracked in git and defines the shape of your app; env vars are per-environment values (often secrets) that override the file at runtime. Moose Runtime loads both at startup, with env vars winning when they overlap.

Concept

Two layers you configure:

1. Project Definition (moose.config.toml) — Project structure, languages, feature flags, and dev infrastructure. Tracked in git.
2. Runtime Configuration (Environment Variables) — How you override the file for each environment (credentials, telemetry flags, hostnames, etc.). Use env vars (.env.prod, .env.dev, .env.local) or your platform’s secrets manager.

Configuration Resolution

MooseStack resolves configuration values in the following order (highest priority first):

1. System Env Vars - MOOSE_* variables set in the shell or platform. Overrides everything.
2. .env.local - Local overrides for development secrets. Gitignored.
3. .env.{env} - Environment profiles (e.g., .env.prod or .env.dev).
4. .env - Global shared defaults.
5. moose.config.toml - Base project configuration file.
6. Defaults - Framework built-in defaults.

Environment Variables

Environment variables are the primary mechanism for managing secrets and differentiating between environments.

Syntax

Pattern: moose.config.toml → MOOSE_{SECTION}__{KEY}

• All env vars are prefixed with MOOSE_.
• SECTION is UPPER_CASE, underscore-separated name of the section in moose.config.toml (e.g., clickhouse_config, features, etc.)
• KEY is the key in the section (e.g., host, workflows, etc.)
• Double underscores (__) separate the section and key.

.env Files

Moose Runtime automatically loads .env files in order of precedence. Files loaded later override values from earlier files.

Configuration Reference

Core Settings

• Project Settings - Top-level project settings and directory structure.
• TypeScript - Specific settings for TypeScript projects.
• Telemetry - Data collection settings.
• Git - Version control integration settings.
• Features - Feature flags to enable or disable capabilities.
• Migrations - Database migration behavior and operations.
• Docker - Custom Dockerfile support for deployment packaging.

Infrastructure

• ClickHouse - OLAP database connection and behavior.
• Redpanda - Streaming platform configuration.
• Redis - Caching and state management layer.
• Temporal - Workflow orchestration engine.
• HTTP Server - Local development server settings.
• State Storage - Migration state storage backend.

Security & Development

• JWT - JSON Web Token validation settings.
• Admin API - Authentication for the Admin API.
• Dev Environment - Local development scripts and networking.