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'"

Key	Env Variable	Type	Default	Description
`on_first_start_script`	`MOOSE_HTTP_SERVER_CONFIG__ON_FIRST_START_SCRIPT`	String	-	Shell command executed once when `moose dev` starts.
`on_reload_complete_script`	`MOOSE_HTTP_SERVER_CONFIG__ON_RELOAD_COMPLETE_SCRIPT`	String	-	Shell command executed after every code/infra reload.

Execution Context

Scripts run from your project root using your system's default shell (usually /bin/sh or bash). You can chain commands using &&.

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. Use ignore_patterns to exclude files generated by lifecycle hooks that you don't want to 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.

File Name	Purpose
`docker-compose.dev.override.yaml`	Adds or overrides services in the generated Docker Compose setup.

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"

Limitations

Do not use this file to configure Moose-managed services (ClickHouse, Redpanda, Redis, Temporal). Use moose.config.toml for those components to avoid configuration conflicts.

Networking Reference

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

Default Ports

Port	Service	Description	Config Key
4000	API Server	Main Ingestion/Consumption APIs	`http_server_config.port`
5001	Management API	Health checks & Metrics	`http_server_config.management_port`
18123	ClickHouse HTTP	OLAP Database (HTTP)	`clickhouse_config.host_port`
9000	ClickHouse Native	OLAP Database (TCP)	`clickhouse_config.native_port`
19092	Redpanda	Kafka Streaming	`redpanda_config.broker`
8080	Temporal UI	Workflow Dashboard	`temporal_config.ui_port`

Service URLs

Access points for local development services:

Service	URL
Main API	`http://localhost:4000`
Management API	`http://localhost:5001/metrics`
OpenAPI Spec	`http://localhost:5001/openapi.yaml`
Temporal UI	`http://localhost:8080`