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. |
Scripts run from your project root using your system's default shell (usually /bin/sh or bash). You can chain commands using &&.
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 ..."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 |