Container Runtime Contract

This document is the project source of truth for Docker image, Compose, and deploy runtime behavior.

Scope

Every long-running service runs in Docker as a non-root numeric user.
Default runtime user and group on mathbox are 1001:1001 unless a module env explicitly overrides them.
Every module owns data/, logs/, conf/, and its compose file.
conf/ mounts stay read-only.
Every service uses restart: unless-stopped.
whatsapp-adapter-api and whatsapp-adapter-app expose GET /healthz.
whatsapp-adapter-waha exposes the vendor GET /ping health endpoint.
whatsapp-adapter-docs exposes GET /healthz.
Cross-module calls use the shared Docker network ${PROJECT_INTERNAL_NETWORK}.

whatsapp-adapter-waha
/app/data
/app/logs
/app/conf
/app/.sessions
/app/.media
whatsapp-adapter-api
/app/data
/app/logs
/app/conf
/app/provider-sessions read-only bind of whatsapp-adapter-waha/sessions for provider history supplement
whatsapp-adapter-app
/app/data
/app/logs
/app/conf
whatsapp-adapter-docs
/app/data
/app/logs
/app/conf

SOPS-encrypted secrets/local/<module>.env is the source of truth for local runtime config.
SOPS-encrypted secrets/prod/<module>.env is the source of truth for deploy runtime config.
Local start materializes <module>/.env.local from secrets/local/<module>.env.
Deploy materializes <module>/.env.server from secrets/prod/<module>.env.
./script/materialize-secret.sh renders plaintext env files into the module runtime location.