From 3de1d3fca547af86ff1b2ff60de20266c40aa269 Mon Sep 17 00:00:00 2001 From: bunker-admin Date: Mon, 30 Mar 2026 11:44:25 -0600 Subject: [PATCH] Rewrite README as visual explainer with screenshots and docs link Bunker Admin --- README.md | 186 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 129 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index 69c8d35e..acb53945 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,156 @@ -# Changemaker Lite +

+ Changemaker Lite +

-A self-hosted political campaign platform that consolidates advocacy email campaigns, geographic mapping, volunteer canvassing, media management, and administration into a single TypeScript stack. Built for organizers who want to own their data. +

Changemaker Lite

-## What Is This? +

+ A self-hosted campaign platform for community organizers who want to own their data. +

-Changemaker Lite gives community organizers the tools they need to: +

+ Documentation · + Website · + Apache 2.0 License +

-- **Run advocacy campaigns** — let supporters look up their elected representatives by postal code and send emails in a few clicks -- **Manage canvassing** — map locations, draw canvassing areas, schedule volunteer shifts, and track door-to-door visits with GPS -- **Host media** — upload campaign videos, share them publicly, and track engagement analytics -- **Build landing pages** — drag-and-drop page builder for campaign microsites -- **Send newsletters** — integrated with Listmonk for opt-in mailing lists -- **Monitor everything** — Prometheus + Grafana observability stack included +--- -The entire platform runs on Docker Compose with a single `.env` file for configuration. +Changemaker Lite consolidates advocacy campaigns, geographic mapping, volunteer canvassing, media management, newsletters, and administration into a single Docker Compose stack. One `.env` file, one command to start, everything under your control. + +

+ Admin Dashboard +

+ +## Why Changemaker Lite? + +Most campaign tools are SaaS platforms that lock you into monthly subscriptions, hold your data hostage, and disappear when funding dries up. Changemaker Lite is different: + +- **Self-hosted** -- runs on any machine with Docker. Your server, your data. +- **All-in-one** -- replaces 5-10 separate tools with a single integrated platform. +- **Free and open source** -- Apache 2.0 licensed. Fork it, modify it, make it yours. +- **Privacy-first** -- no telemetry, no third-party analytics, no data leaving your server. + +## What's Inside + +### Advocacy Campaigns + +Let supporters look up their elected representatives by postal code and send advocacy emails in a few clicks. Track responses, moderate a public response wall, and monitor email delivery. + +

+ Public Campaign Page +

+ +

+ Campaign Management +

+ +### Interactive Map & Canvassing + +Import thousands of addresses, draw canvassing areas, schedule volunteer shifts, and track door-to-door visits with GPS. Volunteers get a full-screen mobile map with real-time location tracking and visit recording. + +

+ Public Map +

+ +

+ Canvass Dashboard +

+ +### Volunteer Portal + +Volunteers get their own portal with shift sign-ups, canvassing assignments, activity tracking, a social calendar, and a friends system to stay connected with their team. + +

+ Volunteer Map +

+ +

+ Volunteer Calendar +

+ +### Media Library & Public Gallery + +Upload campaign videos, manage metadata, schedule publishing, and share them through a public gallery. Includes GDPR-compliant analytics. + +

+ Media Library +

+ +

+ Public Gallery +

+ +### Landing Pages & Email Templates + +Build campaign microsites with a drag-and-drop GrapesJS editor. Design email templates for consistent campaign communications. + +

+ Landing Page Builder +

+ +### SMS Campaigns, Newsletters & More + +Send SMS campaigns via an Android bridge, sync subscribers to Listmonk for newsletters, recognize volunteers on a Wall of Fame leaderboard, and monitor everything with built-in Prometheus + Grafana observability. + +

+ SMS Dashboard +

+ +

+ Wall of Fame +

## Quick Start ```bash -# Clone and switch to the v2 branch +# One-command install (downloads pre-built images, runs config wizard) +curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/v2/scripts/install.sh | bash + +cd ~/changemaker.lite +docker compose up -d +``` + +Or clone and build from source: + +```bash git clone changemaker.lite -cd changemaker.lite -git checkout v2 +cd changemaker.lite && git checkout v2 -# Create your environment file cp .env.example .env -# Edit .env — at minimum set: -# V2_POSTGRES_PASSWORD, REDIS_PASSWORD, -# JWT_ACCESS_SECRET, JWT_REFRESH_SECRET, ENCRYPTION_KEY -# INITIAL_ADMIN_EMAIL, INITIAL_ADMIN_PASSWORD +# Edit .env -- set passwords, JWT secrets, admin credentials -# Start core services docker compose up -d v2-postgres redis api admin - -# Run database migrations and seed docker compose exec api npx prisma migrate deploy docker compose exec api npx prisma db seed ``` Then open **http://localhost:3000** and log in with the admin credentials from your `.env`. -## Architecture - -| Component | Technology | Port | -|-----------|-----------|------| -| **API** | Express.js + Prisma + PostgreSQL | 4000 | -| **Media API** | Fastify + Prisma (shared DB) | 4100 | -| **Admin GUI** | React + Vite + Ant Design + Zustand | 3000 | -| **Reverse Proxy** | Nginx (subdomain routing) | 80 | -| **Database** | PostgreSQL 16 | 5433 | -| **Cache / Queue** | Redis + BullMQ | 6379 | -| **Newsletter** | Listmonk | 9001 | -| **Monitoring** | Prometheus + Grafana + Alertmanager | 9090, 3001 | - -See `CLAUDE.md` for comprehensive architecture documentation, module reference, and troubleshooting. - -## Feature Flags - -Enable optional modules in `.env`: - -```bash -ENABLE_MEDIA_FEATURES=true # Video library + gallery -LISTMONK_SYNC_ENABLED=true # Newsletter subscriber sync -EMAIL_TEST_MODE=true # Route emails to MailHog (dev) -``` - -## Production Deployment - -Changemaker Lite uses [Pangolin](https://github.com/fosrl/pangolin) tunnels for production access (Cloudflare alternative). See the Tunnel page in the admin panel (`/app/tunnel`) for setup instructions. - ## Documentation -- **`CLAUDE.md`** — Full project reference (architecture, modules, ports, patterns) -- **`V2_PLAN.md`** — Development roadmap (Phases 1-14 complete) -- **`SECURITY_AUDIT_2025-02-11.md`** — Security audit findings and remediations -- **`.env.example`** — All 100+ environment variables with descriptions +**Full documentation is available at [cmlite.org/docs/getting-started](https://cmlite.org/docs/getting-started/).** -## Licensing +The docs site covers installation, configuration, all features, architecture details, production deployment with Pangolin tunnels, and troubleshooting. It is the authoritative and up-to-date reference for Changemaker Lite. -This project is licensed under the [Apache License 2.0](https://opensource.org/license/apache-2-0). +## Architecture at a Glance + +| Layer | Technology | +|-------|-----------| +| API | Express.js + Prisma + PostgreSQL 16 | +| Media API | Fastify + Prisma (shared DB) | +| Frontend | React + Vite + Ant Design + Zustand | +| Reverse Proxy | Nginx (subdomain routing) | +| Cache & Queue | Redis + BullMQ | +| Newsletter | Listmonk | +| Monitoring | Prometheus + Grafana + Alertmanager | +| Tunneling | Pangolin (self-hosted Cloudflare alternative) | + +The entire stack runs on Docker Compose. Enable optional modules (media, newsletters, SMS, monitoring) with feature flags in `.env`. + +## License + +[Apache License 2.0](https://opensource.org/license/apache-2-0) ## AI Disclaimer