Docker Deployment

Run the full Moca stack with Docker Compose. All five Moca processes and their backing services are defined in a single Compose file.

Prerequisites

• Docker Engine 24+
• 2 GB RAM minimum (4 GB recommended for production)

Quick Start

# Clone the repository (or use your own project directory)
git clone https://github.com/osama1998h/moca.git
cd moca

# Copy the example environment file
cp .env.example .env

# Edit .env with your configuration
$EDITOR .env

Using Pre-built Images

Pull the latest release images from the GitHub Container Registry:

docker pull ghcr.io/osama1998h/moca/moca-server:latest
docker pull ghcr.io/osama1998h/moca/moca-worker:latest
docker pull ghcr.io/osama1998h/moca/moca-scheduler:latest
docker pull ghcr.io/osama1998h/moca/moca-outbox:latest
docker pull ghcr.io/osama1998h/moca/moca:latest

Replace latest with a specific release tag (e.g., v0.2.0) for reproducible deployments.

Using Local Builds

Build all images from source using the production Compose file:

docker compose -f docker-compose.example.yml build

Start the Stack

docker compose up -d

This starts:

• moca-server — HTTP + WebSocket API gateway
• moca-worker — background job consumer
• moca-scheduler — cron job dispatcher
• moca-outbox — transactional outbox poller
• moca-cli — one-shot init container (runs migrations then exits)
• postgres — PostgreSQL 16
• redis — Redis 7
• meilisearch — Meilisearch v1.12

Initialize

Once the stack is healthy, create your first site:

docker compose exec moca-server moca site create mysite

Environment Configuration

Key variables in .env:

Variable	Purpose	Example
MOCA_DB_HOST	PostgreSQL host	postgres
MOCA_DB_PASSWORD	PostgreSQL password	changeme
MOCA_REDIS_ADDR	Redis address	redis:6379
MOCA_SEARCH_HOST	Meilisearch URL	http://meilisearch:7700
MOCA_SEARCH_API_KEY	Meilisearch master key	your-secret-key
MOCA_SECRET_KEY	Application secret (JWT signing)	random-64-char-string
MOCA_DOMAIN	Public domain name	mysite.example.com

Scaling Workers

Scale the worker pool to handle higher job throughput without restarting other services:

docker compose up -d --scale moca-worker=3

Data Persistence

Moca uses named Docker volumes for all stateful data:

• moca_postgres_data — PostgreSQL data directory
• moca_redis_data — Redis append-only file
• moca_meilisearch_data — Meilisearch indexes

Back up all volumes:

moca backup create --dest /var/backups/moca

Upgrading

With pre-built images:

docker compose pull
docker compose up -d

With local builds:

docker compose -f docker-compose.example.yml build
docker compose up -d

Both approaches recreate only the containers whose images have changed. Database migrations run automatically on startup via the init container.

Resource Limits

Each service in docker-compose.example.yml includes a deploy.resources section with CPU and memory limits. Adjust these in your Compose file to match your host capacity.

Example (from the production Compose file):

services:
  moca-server:
    deploy:
      resources:
        limits:
          cpus: "1.0"
          memory: 512M
        reservations:
          memory: 256M