Dev Environment Configuration

This reference covers configuration options specific to the local development workflow (moose dev), including lifecycle hooks, Docker infrastructure extensions, and network defaults.

Lifecycle Hooks

Configure shell commands to run automatically during the development server's lifecycle. These are defined within the [http_server_config] section of your configuration.

[http_server_config]# Script to run once on first starton_first_start_script = "echo 'Dev server started'" # Script to run after every reload completeson_reload_complete_script = "echo 'Reload complete'"

Common Examples

Sync External Tables on Start

on_first_start_script = "moose db pull --clickhouse-url $REMOTE_DB_URL"

Regenerate Clients on Reload

on_reload_complete_script = "openapi-generator-cli generate -i .moose/openapi.yaml ..."

File Watcher

The dev server watches your project and hot-reloads when you save changes.

• TypeScript projects: Reloads are driven by TypeScript compilation. The compiler runs in watch mode; when you save a file, an incremental compile runs. Only after a successful compile does Moose re-plan and apply infrastructure changes. Compilation errors block reloads (fix errors in your code to continue). Compiled output goes to your tsconfig.json outDir or .moose/compiled. See Moose Dev for details.
• Python projects: A file watcher detects changes and triggers reloads directly.

Use ignore_patterns to exclude files (e.g. generated by lifecycle hooks) that should not trigger reloads.

[watcher_config]# Patterns use standard glob syntaxignore_patterns = ["generated/**", "*.gen.ts"]

Debugging Data Flow

To debug data as it flows through your pipeline, use the --log-payloads flag:

moose dev --log-payloads

This logs payloads at three key points with searchable prefixes:

• PAYLOAD:INGEST - Data received at ingest API
• PAYLOAD:STREAM_IN - Data before streaming function
• PAYLOAD:STREAM_OUT - Data after streaming function

All logs appear in Moose logs and can be viewed using moose logs --tail.

Docker Infrastructure Extensions

Extend the default Moose development infrastructure by creating a specific override file in your project root.

Usage

Create docker-compose.dev.override.yaml to add services like PostgreSQL or monitoring tools. Moose automatically detects and merges this file when running moose dev.

# docker-compose.dev.override.yamlservices:  postgres:    image: postgres:16    environment:      POSTGRES_PASSWORD: mypassword    ports:      - "5432:5432"

Externally Managed Tables

When working with tables marked as EXTERNALLY_MANAGED (tables that exist in a production database but are managed outside Moose), you can configure the dev environment to create local mirror tables for development and testing.

Configuration

[dev.externally_managed.tables]# Create local mirror tables for EXTERNALLY_MANAGED tablescreate_local_mirrors = true # Number of sample rows to seed (0 = schema only, no data)sample_size = 1000 # Re-create tables on every dev server startrefresh_on_startup = false

Remote ClickHouse Connection

To mirror data from a production or staging database, configure a remote ClickHouse connection:

[dev.remote_clickhouse]host = "your-clickhouse-host.example.com"port = 8443database = "production_db"use_ssl = trueprotocol = "http"

Networking Reference

Reference for default ports and URLs used by the Moose Runtime in development mode.

Default Ports

Service URLs

Access points for local development services: