stack/docs/federation/SETUP.md

Federated Tier Setup Guide

What is the federated tier?

The federated tier is designed for multi-user and multi-host deployments. It consists of PostgreSQL 17 with pgvector extension (for embeddings and RAG), Valkey for distributed task queueing and caching, and a shared configuration across multiple Mosaic gateway instances. Use this tier when running Mosaic in production or when scaling beyond a single-host deployment.

Prerequisites

• Docker and Docker Compose installed
• Ports 5433 (PostgreSQL) and 6380 (Valkey) available on your host (or adjust environment variables)
• At least 2 GB free disk space for data volumes

Start the federated stack

Run the federated overlay:

docker compose -f docker-compose.federated.yml --profile federated up -d

This starts PostgreSQL 17 with pgvector and Valkey 8. The pgvector extension is created automatically on first boot.

Verify the services are running:

docker compose -f docker-compose.federated.yml ps

Expected output shows postgres-federated and valkey-federated both healthy.

Configure mosaic for federated tier

Create or update your mosaic.config.json:

{
  "tier": "federated",
  "database": "postgresql://mosaic:mosaic@localhost:5433/mosaic",
  "queue": "redis://localhost:6380"
}

If you're using environment variables instead:

export DATABASE_URL="postgresql://mosaic:mosaic@localhost:5433/mosaic"
export REDIS_URL="redis://localhost:6380"

Verify health

Run the health check:

mosaic gateway doctor

Expected output (green):

Tier: federated  Config: mosaic.config.json
  ✓ postgres         localhost:5433       (42ms)
  ✓ valkey           localhost:6380       (8ms)
  ✓ pgvector         (embedded)           (15ms)

For JSON output (useful in CI/automation):

mosaic gateway doctor --json

Troubleshooting

Port conflicts

Symptom: bind: address already in use

Fix: Stop the base dev stack first:

docker compose down
docker compose -f docker-compose.federated.yml --profile federated up -d

Or change the host port with an environment variable:

PG_FEDERATED_HOST_PORT=5434 VALKEY_FEDERATED_HOST_PORT=6381 \
  docker compose -f docker-compose.federated.yml --profile federated up -d

pgvector extension error

Symptom: ERROR: could not open extension control file

Fix: pgvector is created at first boot. Check logs:

docker compose -f docker-compose.federated.yml logs postgres-federated | grep -i vector

If missing, exec into the container and create it manually:

docker exec <postgres-federated-id> psql -U mosaic -d mosaic -c "CREATE EXTENSION vector;"

Valkey connection refused

Symptom: Error: connect ECONNREFUSED 127.0.0.1:6380

Fix: Check service health:

docker compose -f docker-compose.federated.yml logs valkey-federated

If Valkey is running, verify your firewall allows 6380. On macOS, Docker Desktop may require binding to host.docker.internal instead of localhost.