86 lines
3.4 KiB
Markdown
86 lines
3.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```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
|
|
|
|
## Licensing
|
|
|
|
This project is licensed under the [Apache License 2.0](https://opensource.org/license/apache-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.
|