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.
What Is This?
Changemaker Lite gives community organizers the tools they need to:
- 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.
Quick Start
# Clone and switch to the v2 branch
git clone <repo-url> changemaker.lite
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
# 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:
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 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
Licensing
This project is licensed under the Apache License 2.0.
AI Disclaimer
AI tools were used to assist in the creation of this project. All generated code has been reviewed. Users should test all functionality to ensure it meets their requirements.