Guide Configuration - osama1998H/Moca GitHub Wiki

Configuration Guide

How moca.yaml is organized, how values are resolved, and which settings matter most in local development.

Canonical Layout

The current config shape is organized by responsibility:

  • project and apps for project metadata and installed apps
  • infrastructure for PostgreSQL, Redis, search, Kafka, and storage
  • development for local server, Desk, logs, and profiling
  • observability for metrics and tracing
  • notification, scheduler, backup, production, and optional staging for operational behavior

Minimal local example:

moca: ">=0.1.0"

project:
  name: my-project
  version: 1.0.0

infrastructure:
  database:
    driver: postgres
    host: ${DB_HOST:-localhost}
    port: ${DB_PORT:-5432}
    system_db: ${DB_NAME:-moca_dev}
    user: ${DB_USER:-moca}
    password: ${DB_PASSWORD}
  redis:
    host: ${REDIS_HOST:-localhost}
    port: ${REDIS_PORT:-6379}
    db_cache: 0
    db_queue: 1
    db_session: 2
    db_pubsub: 3
  search:
    engine: meilisearch
    host: ${MEILI_HOST:-localhost}
    port: ${MEILI_PORT:-7700}

development:
  port: 8000
  desk_port: 3000
  auto_reload: true
  desk_dev_server: true
  enable_pprof: false

observability:
  metrics:
    enabled: true
    path: /metrics
  tracing:
    enabled: false

Environment Variable Expansion

Use ${VAR_NAME} or ${VAR_NAME:-default} in any string value. Expansion happens before validation.

Common Development Toggles

  • development.port controls the local API server port
  • development.desk_port controls the Vite dev server used by moca desk dev
  • development.desk_dev_server: true proxies Desk requests to Vite instead of serving built assets
  • development.enable_pprof: true enables /debug/pprof/* so moca dev profile can capture profiles

Observability Setup

Prometheus metrics are enabled by default and exposed on /metrics unless you override observability.metrics.path.

Tracing is opt-in:

observability:
  tracing:
    enabled: true
    exporter: otlp
    endpoint: localhost:4317
    insecure: true
    sample_rate: 1.0

For local development, the repository docker-compose.yml includes Jaeger on localhost:16686 with OTLP ingest on localhost:4317.

CLI Commands

moca config get observability.metrics.path
moca config set notification.email.smtp.host smtp.example.com
moca config list
moca config validate
moca doctor --site mysite --verbose

Related