Resilient, independent, self-hosted communications infrastructure designed for geographically distributed community movements, mutual aid networks, and public organizations.
When commercial platforms suffer outages, change ownership, ban organizers, or throttle access, a community's voice must not go silent.
The Community Communications Stack is not another chat application—it is an integrated deployment and operational layer combining proven, battle-tested open-source software (Matrix Synapse, Element Web, Caddy, Restic, and mautrix-whatsapp) into a unified, easy-to-run system that volunteer non-specialists can deploy, manage, and recover.
- 📢 Public Announcements: Save announcements in SQLite and publish public HTML, RSS, Atom, and JSON Feed output. Matrix, ActivityPub, and email adapters are prototypes; they are not enabled by default or verified against live services.
- 🛡️ Privacy by Separation: Public bulletins, open community discussion, and sensitive internal coordination live in distinct, strictly isolated zones. Internal rooms are never exposed or bridged.
- 📱 Optional WhatsApp Bridge: A separately configured
mautrix-whatsappintegration is available; it is not part of the announcement publishing UI and has not been live-service verified here. - 📦 Off-Grid & Offline Continuity: Generate self-contained offline HTML/JSON archives with one command. Distribute them on USB drives or local Wi-Fi captive portals (Raspberry Pi/OpenWrt) during internet blackouts.
- 🔒 True Disaster Recovery: Client-side encrypted backups (restic) and verified non-destructive restore drills ensure that complete server loss does not destroy community identity or history.
- ⚙️ Friendly Unified CLI: Manage the entire infrastructure with a single Python command:
community-stack. All outputs, logs, and diagnostic reports feature automated secret redaction.
The stack is organized into four modular layers with isolated Docker networks:
[ Public Internet ]
│ (Ports 80, 443)
▼
┌─────────────────┐
│ Caddy Ingress │ (Automated ACME TLS)
└────────┬────────┘
│ (proxy_net)
┌─────────┼─────────────────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Landing │ │ Element │ │ Synapse │ (Matrix Homeserver)
│ Page │ │ Web │ └────┬────┘
└─────────┘ └─────────┘ │ (matrix_internal - Isolated)
▼
┌──────────┐
│PostgreSQL│ (Database)
└──────────┘
▲
│ (bridge_net)
┌──────────┐
│ WhatsApp │ (mautrix-whatsapp, Optional)
│ Bridge │
└──────────┘
| Layer | Components | Role |
|---|---|---|
| Layer A: Core Services | Matrix Synapse, Element Web, Public Portal | Open, federated community chat & web client |
| Layer B: Distribution Adapters | Local HTML/RSS/Atom/JSON Feed (working); Matrix (opt-in); ActivityPub/email (experimental) | Matrix uses automated test doubles and still needs staging verification; SMS/voice remain planned |
| Layer C: Operations & Ingress | Caddy, Docker Compose, Ansible, community-stack CLI |
Automated TLS, networking, host configuration |
| Layer D: Resilience & Continuity | Restic, Standby Host Playbook, Offline HTML Exporter | Surviving outages, provider eviction, server loss |
This project uses uv for high-speed, reproducible Python virtual environments and dependency management.
git clone https://github.com/your-org/community-stack.git
cd community-stack
# Sync virtual environment and dependencies
uv sync --all-extras --dev# Creates community-stack.yaml, data directories, and .env with secure random keys
uv run community-stack init# Run comprehensive configuration and environment checks
uv run community-stack check
# Preview the dry-run execution plan without modifying the host
uv run community-stack planThe community-stack CLI provides a single, predictable interface for all operational tasks:
Usage: community-stack [OPTIONS] COMMAND [ARGS]...
Infrastructure & Lifecycle:
init Initialize local configuration, directories, and secure credentials
check Validate configuration against JSON Schema, secrets, and system tools
plan Read-only dry-run preview of services, networks, and ingress routes
install Deploy enabled services to the host via Docker Compose
status Report running container health, status, and port bindings
logs Stream or tail service logs (e.g. community-stack logs matrix -f)
upgrade Safely upgrade a service with an automatic pre-upgrade snapshot
doctor Run non-destructive diagnostics with automated secret redaction
Backup & Recovery:
backup Create an encrypted backup snapshot (with DB dump)
backup verify Verify archive completeness, manifest, and cryptographic integrity
restore Safely restore a snapshot to an isolated directory (--confirm required)
Broadcast & Channels:
announce Draft, preview, publish, list, update, retract, and track announcements
subscribers Manage opt-in email and SMS lists: export, erase, test-send, instant opt-out
connect Show the stable /connect contact page, QR codes and identity package
bridge Inspect WhatsApp bridge health or trigger the emergency killswitch
archive Export and verify zero-dependency offline HTML archives
# Create an unpublished draft
uv run community-stack announce draft \
--title "Mutual Aid Distribution Station Open" \
--body "Supplies and hot meals available at City Hall until 8pm." \
--author "Logistics Working Group"
# Preview it, then explicitly publish it
uv run community-stack announce preview ann_...
uv run community-stack announce publish ann_...community-stack announce create remains available as a compatibility shortcut that creates and immediately publishes. The default enabled destination is the local public web archive and its RSS, Atom, and JSON feeds; no live external channel delivery is implied.
For configured social platforms without an active connector, publication prepares
the post for a person to publish. Inspect channel states and their attempt history
with uv run community-stack announce deliveries <id>, then record what happened, for example:
uv run community-stack announce outcome ann_... instagram published \
--post-url "https://www.instagram.com/p/..." \
--actor "Organizer name"Use updated or withdrawn when recording follow-up tasks. Published and updated
outcomes require an HTTPS post URL; every outcome requires the responsible
person's name.
The authenticated organizer interface is deployed at https://community.example.org/admin. Configure COMMUNITY_STACK_ADMIN_SETUP_TOKEN in the protected .env file before the first deployment, visit /admin/setup once, and remove the setup token after creating the administrator. The interface does not provide infrastructure administration or shell access.
# Compatibility shortcut for immediate publication
uv run community-stack announce create \
--title "Mutual Aid Distribution Station Open" \
--body "Supplies and hot meals available at City Hall until 8pm." \
--author "Logistics Working Group" \
--tags "mutual-aid,emergency"# Create snapshot
uv run community-stack backup
# Verify integrity
uv run community-stack backup verifyuv run community-stack archive export -o backups/offline_announcements.zip
uv run community-stack archive verify backups/offline_announcements.zip# Halts WhatsApp bridge immediately while keeping Matrix 100% operational
uv run community-stack bridge disable --confirm| Document | Description |
|---|---|
| 📋 Design Specification | Architectural baseline, principles, and roadmap milestones |
| 🏛️ System Architecture | Four-layer architecture, profiles, and service topologies |
| 🛡️ Threat Model | 10 threat vectors, mitigations, residual risks, and non-guarantees |
| 🚀 Deployment Guide | Step-by-step installation on clean Debian 12 / Ubuntu VPS |
| 💾 Backup & Recovery Runbook | Disaster recovery, off-host S3 backups, and restore drills |
| 💬 WhatsApp Integration Guide | mautrix-whatsapp setup, allowlisted bridging, and privacy risks |
| 📡 Accessible Channels | Channel prototypes and evaluation for ActivityPub, email, SMS, and IVR |
| 🌐 Multi-Host Resilience & Offline Continuity | Warm standby host provisioning, captive portals, and Meshtastic |
| 📘 Operator Handbook | Daily maintenance, incident response runbooks, and decommissioning |
| 🤝 Governance & Handover | Two-person rule, credential escrow, and license attribution |
| 📐 Architecture Decisions (ADRs) | Accepted ADRs for homeserver, ingress, backup, and storage choices |
The automated test suite covers schema validation, secret redaction, CLI commands, container service configurations, and disaster recovery:
# Run full test suite with coverage
uv run pytest --cov=community_stack --cov-report=term-missing
# Run code style & lint checks
uv run ruff check .
uv run ruff format --check .- Automated tests cover the announcement lifecycle, channel failure isolation and safe retries, admin authentication/CSRF, configuration, deployment files, and recovery. Matrix live delivery requires a separate staging check.
- CI tests Python 3.10, 3.11, 3.12, and 3.13.
We welcome contributions from organizers, developers, and infrastructure specialists! Please review CONTRIBUTING.md and SECURITY.md before opening pull requests or reporting security issues.
This project is licensed under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).
All upstream container software (Synapse, Element, Caddy, PostgreSQL, mautrix-whatsapp, Restic) retain their respective open-source licenses. See docs/governance.md for complete attribution.