<p align="center">
  <img src="mkdocs/docs/assets/logo.png" alt="Changemaker Lite" width="120" />
</p>

<h1 align="center">Changemaker Lite</h1>

<p align="center">
  A self-hosted campaign platform for community organizers who want to own their data.
</p>

<p align="center">
  <a href="https://cmlite.org/docs/getting-started/">Documentation</a> &middot;
  <a href="https://cmlite.org">Website</a> &middot;
  <a href="https://opensource.org/license/apache-2-0">Apache 2.0 License</a>
</p>

---

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.

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/admin-dashboard.png" alt="Admin Dashboard" width="800" />
</p>

## 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.

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/public-campaigns.png" alt="Public Campaign Page" width="800" />
</p>

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/influence-campaigns.png" alt="Campaign Management" width="800" />
</p>

### 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.

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/public-map.png" alt="Public Map" width="800" />
</p>

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/canvass-dashboard.png" alt="Canvass Dashboard" width="800" />
</p>

### 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.

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/volunteer-dashboard.png" alt="Volunteer Map" width="800" />
</p>

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/volunteer-calendar.png" alt="Volunteer Calendar" width="800" />
</p>

### Media Library & Public Gallery

Upload campaign videos, manage metadata, schedule publishing, and share them through a public gallery. Includes GDPR-compliant analytics.

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/media-library.png" alt="Media Library" width="800" />
</p>

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/public-gallery.png" alt="Public Gallery" width="800" />
</p>

### Landing Pages & Email Templates

Build campaign microsites with a drag-and-drop GrapesJS editor. Design email templates for consistent campaign communications.

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/landing-pages.png" alt="Landing Page Builder" width="800" />
</p>

### 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.

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/sms-dashboard.png" alt="SMS Dashboard" width="800" />
</p>

<p align="center">
  <img src="mkdocs/docs/assets/images/screenshots/features/public-wall-of-fame.png" alt="Wall of Fame" width="800" />
</p>

## Quick Start

### Production (pre-built images)

```bash
# 1. One-command install: checks host ports, downloads tarball, runs config wizard
curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash

# 2. Start services (first pull ~3 min + ~90s stabilization)
cd ~/changemaker.lite && docker compose up -d

# 3. Verify the install
bash scripts/test-deployment.sh --wait 60
```

The installer checks your host's port availability before extracting — no more half-started stacks from cockpit on `:9090` or other surprises. The generated admin password is printed to stdout **and** saved to `data/admin-credentials.txt` (mode 0600). See [Prerequisites](https://cmlite.org/docs/getting-started/prerequisites/) for what you need lined up first.

### Development (source)

```bash
git clone <repo-url> changemaker.lite
cd changemaker.lite

cp .env.example .env
# Edit .env -- set passwords, JWT secrets, admin credentials

docker compose up -d v2-postgres redis api admin
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`.

### Useful tools

```bash
bash scripts/validate-env.sh          # re-check .env + host ports
bash scripts/test-deployment.sh       # full deployment health sweep
bash scripts/pangolin-teardown.sh     # wipe tunnel org before reinstall (dry-run by default)
bash scripts/ccp-deregister.sh        # deregister from Changemaker Control Panel (dry-run by default)
```

## Documentation

**Full documentation is available at [cmlite.org/docs/getting-started](https://cmlite.org/docs/getting-started/).**

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.

## 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

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.
