From 822ce89db7613e6aa3b060f3dd177154c7a0878a Mon Sep 17 00:00:00 2001 From: Guido X Jansen Date: Sat, 14 Feb 2026 15:06:17 +0100 Subject: [PATCH] feat(global): add global aggregator Docker Compose override (#5) Override file that layers on docker-compose.yml to configure global aggregator mode: COMMUNITY_MODE=global, PostgreSQL tuning for larger datasets, and higher resource limits on all services. README updated with production deployment guide, headless API instructions, and global aggregator section. --- README.md | 81 +++++++++++++++++++++++++++++++++++++-- docker-compose.global.yml | 44 +++++++++++++++++++++ 2 files changed, 122 insertions(+), 3 deletions(-) create mode 100644 docker-compose.global.yml diff --git a/README.md b/README.md index 9d229b0..5ef1524 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,8 @@ Docker Compose configurations and documentation for running Barazo -- a federate | Profile | Use Case | File | Status | |---------|----------|------|--------| | **Development** | Local dev (infrastructure only) | `docker-compose.dev.yml` | Available | -| **Single Forum** | One community, production | `docker-compose.yml` | Planned | -| **Global Aggregator** | Cross-community aggregator | `docker-compose.global.yml` | Planned | +| **Single Forum** | One community, production | `docker-compose.yml` | Available | +| **Global Aggregator** | Cross-community aggregator | `docker-compose.global.yml` | Available | --- @@ -171,7 +171,82 @@ docker compose -f docker-compose.dev.yml logs postgres ## Production Deployment -Production Docker Compose with Caddy SSL, two-network segmentation, and health checks will be added in a future release. +Deploy a single Barazo community with automatic SSL via Caddy. + +### Quick Start (Production) + +```bash +git clone https://github.com/barazo-forum/barazo-deploy.git +cd barazo-deploy + +# Configure +cp .env.example .env +nano .env # Set domain, passwords, community DID, etc. + +# Start +docker compose up -d + +# Verify +docker compose ps # All services should be "healthy" +docker compose logs -f # Watch startup logs +``` + +Your forum will be available at `https://your-domain.com` once Caddy obtains the SSL certificate (automatic via Let's Encrypt). + +### Production Services + +| Service | Image | Network | Purpose | +|---------|-------|---------|---------| +| **caddy** | `caddy:2-alpine` | frontend | Reverse proxy, automatic SSL (only exposed service: ports 80, 443) | +| **barazo-api** | `ghcr.io/barazo-forum/barazo-api` | frontend + backend | AppView backend (Fastify, REST API, firehose indexing) | +| **barazo-web** | `ghcr.io/barazo-forum/barazo-web` | frontend | Next.js frontend | +| **postgres** | `pgvector/pgvector:pg16` | backend | PostgreSQL 16 with pgvector | +| **valkey** | `valkey/valkey:8-alpine` | backend | Redis-compatible cache | +| **tap** | `ghcr.io/bluesky-social/indigo/tap` | backend | AT Protocol firehose consumer | + +Two-network segmentation: PostgreSQL and Valkey are on the `backend` network only, unreachable from Caddy or the frontend. + +### Headless API (No Frontend) + +To run without the frontend container (e.g., custom frontend or API-only access): + +```bash +docker compose up -d postgres valkey tap caddy barazo-api +``` + +Update the Caddyfile to remove or adjust the frontend route as needed. + +--- + +## Global Aggregator + +The global aggregator indexes **all** Barazo communities across the AT Protocol network. It uses the same codebase as a single community but with different configuration and higher resource allocation. + +### Differences from Single Community + +| Aspect | Single Community | Global Aggregator | +|--------|-----------------|-------------------| +| `COMMUNITY_MODE` | `single` | `global` | +| Indexes | One community's records | All `forum.barazo.*` records network-wide | +| Features | Standard forum | Cross-community search, reputation aggregation | +| PostgreSQL | 1 GB RAM | 4 GB RAM (more data) | +| API | 1 GB RAM | 2 GB RAM (more indexing) | +| Minimum server | 2 vCPU / 4 GB RAM | 4 vCPU / 8 GB RAM | + +### Quick Start (Global Aggregator) + +```bash +cp .env.example .env +nano .env # Set COMMUNITY_MODE=global, domain, passwords + +# Start with the global override +docker compose -f docker-compose.yml -f docker-compose.global.yml up -d +``` + +The global override file (`docker-compose.global.yml`) layers on top of the production compose to: +- Set `COMMUNITY_MODE=global` on the API +- Apply PostgreSQL performance tuning (`shared_buffers`, `effective_cache_size`, `work_mem`) +- Set higher memory and CPU limits on all services ### Minimum Requirements diff --git a/docker-compose.global.yml b/docker-compose.global.yml new file mode 100644 index 0000000..d6d8e82 --- /dev/null +++ b/docker-compose.global.yml @@ -0,0 +1,44 @@ +# Barazo Global Aggregator -- Docker Compose Override +# +# Extends docker-compose.yml for global aggregator mode. +# The aggregator indexes ALL Barazo communities across the network. +# +# Usage: +# cp .env.example .env +# # Edit .env: set COMMUNITY_MODE=global, increase resource allocation +# docker compose -f docker-compose.yml -f docker-compose.global.yml up -d +# +# Minimum requirements: 4 vCPU, 8 GB RAM, 100 GB SSD +# See README.md "Global Aggregator" section for details. + +services: + # Override API to global mode + barazo-api: + environment: + COMMUNITY_MODE: global + # Higher resource limits for indexing all communities + mem_limit: 2g + cpus: 2.0 + + # Larger database for cross-community data + postgres: + mem_limit: 4g + cpus: 2.0 + # Tune PostgreSQL for higher load + command: > + postgres + -c shared_buffers=1GB + -c effective_cache_size=3GB + -c work_mem=16MB + -c maintenance_work_mem=256MB + -c max_connections=200 + + # Larger cache for cross-community queries + valkey: + mem_limit: 1g + cpus: 0.5 + + # Tap handles full network firehose (higher resource usage) + tap: + mem_limit: 1g + cpus: 1.0 -- 2.51.2