Reference Configuration - osama1998H/Moca GitHub Wiki

Configuration Reference

Reference for the current moca.yaml structure used by the server and CLI.

Top-Level Keys

Key Purpose
moca Required framework version / constraint string
project Project metadata such as name and version
apps Installed app sources and version pins
infrastructure PostgreSQL, Redis, Kafka, search, and object storage settings
development Local server, Desk, worker, log, and profiling options
observability Metrics and tracing settings
notification Email delivery provider configuration
scheduler moca-scheduler enablement and tick interval
backup Backup destination, retention, encryption, and schedule
production Production port, proxy, TLS, workers, and process manager
staging Optional overrides layered on top of another environment

Example Structure

moca: ">=0.1.0"

project:
  name: my-project
  version: 1.0.0

apps:
  crm:
    source: github.com/moca-apps/crm
    version: "^1.2.0"

infrastructure:
  database:
    driver: postgres
    host: localhost
    port: 5432
    system_db: moca_dev
    user: ${DB_USER}
    password: ${DB_PASSWORD}
    pool_size: 20
  redis:
    host: localhost
    port: 6379
    password: ${REDIS_PASSWORD}
    db_cache: 0
    db_queue: 1
    db_session: 2
    db_pubsub: 3
  search:
    engine: meilisearch
    host: localhost
    port: 7700
    api_key: ${MEILI_API_KEY}
  kafka:
    enabled: false
    brokers: []
  storage:
    driver: s3
    endpoint: http://localhost:9000
    bucket: moca-dev
    access_key: ${MINIO_ACCESS_KEY}
    secret_key: ${MINIO_SECRET_KEY}

development:
  port: 8000
  desk_port: 3000
  workers: 1
  log_dir: logs
  auto_reload: true
  desk_dev_server: true
  enable_pprof: false

observability:
  metrics:
    enabled: true
    path: /metrics
  tracing:
    enabled: false
    exporter: otlp
    endpoint: localhost:4317
    insecure: true
    sample_rate: 1.0

notification:
  email:
    provider: smtp
    smtp:
      host: smtp.example.com
      port: 587
      user: ${SMTP_USER}
      password: ${SMTP_PASSWORD}
      from_name: Moca
      from_addr: [email protected]
      use_tls: true

scheduler:
  enabled: true
  tick_interval: 30s

backup:
  encrypt: true
  encryption_key: ${MOCA_ENCRYPTION_KEY}
  schedule: "0 2 * * *"
  destination:
    driver: s3
    bucket: moca-backups
    prefix: nightly/
  retention:
    daily: 7
    weekly: 4
    monthly: 12

production:
  port: 8000
  workers: "4"
  process_manager: systemd
  log_level: info
  proxy:
    engine: caddy
  tls:
    provider: acme
    email: [email protected]

staging:
  inherits: production
  port: 8080

Infrastructure

infrastructure.database

Key Type Notes
driver string Current runtime expects PostgreSQL
host string Database host
port int Database port
system_db string Shared/system database name
user string Supports ${ENV_VAR} expansion
password string Supports ${ENV_VAR} expansion
pool_size int Per-site pool size

infrastructure.redis

Key Type Notes
host string Redis host
port int Redis port
password string Optional AUTH password
db_cache int Cache DB index
db_queue int Queue DB index
db_session int Session DB index
db_pubsub int Pub/sub DB index

infrastructure.search

Key Type Notes
engine string Search backend name, typically meilisearch
host string Search host
port int Search port
api_key string Optional Meilisearch key

infrastructure.kafka

Key Type Notes
enabled bool When omitted or false, Kafka checks and publishing stay disabled
brokers array Broker addresses such as ["localhost:9092"]

infrastructure.storage

Key Type Notes
driver string s3 or local
endpoint string S3-compatible endpoint such as MinIO
bucket string Bucket name
access_key string Supports ${ENV_VAR} expansion
secret_key string Supports ${ENV_VAR} expansion

Development

Key Type Notes
log_dir string Relative paths resolve from the project root
port int moca-server port for local development
workers int Local worker count
desk_port int Vite dev-server port
auto_reload bool Hot reload behavior
desk_dev_server bool Proxy /desk to the Vite server instead of serving static assets
enable_pprof bool Enables /debug/pprof/* endpoints

Observability

observability.metrics

Key Type Default
enabled bool true when omitted
path string /metrics

observability.tracing

Key Type Default
enabled bool false
exporter string otlp
endpoint string localhost:4317
insecure bool true when omitted
sample_rate float 1.0

Notification Delivery

notification.email configures document-triggered email delivery.

notification.email.smtp

Key Type Notes
host string SMTP server hostname
port int Defaults to 587 when unset
user string Supports ${ENV_VAR} expansion
password string Supports ${ENV_VAR} expansion
from_name string Display name
from_addr string Sender email address
use_tls bool Enables STARTTLS

notification.email.ses

Key Type Notes
region string AWS region
from_addr string Verified SES sender address

Notes:

  • provider: smtp uses the SMTP block
  • provider: ses uses the SES block
  • when no provider is configured, notifications remain in-app only

Backup Encryption

The backup CLI resolves the encryption key in this order:

  1. --encryption-key
  2. backup.encryption_key
  3. MOCA_ENCRYPTION_KEY

moca backup create --encrypt writes an encrypted .enc artifact. This is separate from field encryption for document Password fields, which is controlled by the server-side MOCA_ENCRYPTION_KEY environment variable.

Environment Variable Expansion

All string values support ${VAR} and ${VAR:-default} syntax before validation.

Related