This reference covers configuration options specific to the local development workflow (moose dev), including lifecycle hooks, Docker infrastructure extensions, and network defaults.
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. |
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 ..."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.
Scripts run from your project root using your system's default shell (usually /bin/sh or bash). You can chain commands using &&.
[watcher_config]# Patterns use standard glob syntaxignore_patterns = ["generated/**", "*.gen.ts"]To debug data as it flows through your pipeline, use the --log-payloads flag:
moose dev --log-payloadsThis logs payloads at three key points with searchable prefixes:
PAYLOAD:INGEST - Data received at ingest APIPAYLOAD:STREAM_IN - Data before streaming functionPAYLOAD:STREAM_OUT - Data after streaming functionAll logs appear in Moose logs and can be viewed using moose logs --tail.
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. |
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"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.
Reference for default ports and URLs used by the Moose Runtime in development mode.
| 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 |
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 |