Skip to content

Getting Started

Changemaker Lite is a self-hosted campaign platform that runs entirely on Docker. This guide takes you from zero to a working deployment — whether you're evaluating locally or launching for a live campaign.

Need help getting set up?

Bunker Operations provides managed infrastructure and hands-on setup assistance for organizations running Changemaker Lite. We handle domains, tunnels, SMTP, and servers so you can focus on your campaign. Get in touch: bnkops.com | admin@bnkops.ca

What You'll Need

Before deploying, gather the essentials. The requirements differ depending on whether you're running a quick local test or a production deployment serving real users.

Development (Local Testing)

All you need is Docker — no domain, tunnel, or SMTP required:

  • Docker 24+ & Compose v2

    The only hard requirement. All 30+ services run as containers.

  • OpenSSL

    Used by the config wizard to auto-generate 21 secrets (JWT, encryption keys, passwords).

  • 2 GB RAM / 10 GB Disk

    Minimum for core services. 4 GB recommended if enabling media, chat, or monitoring.

MailHog captures all emails locally

In dev mode, every outbound email is caught by MailHog at http://localhost:8025 — no SMTP provider needed.

Production Deployment

For a deployment that serves real users, you'll also need:

  • A Domain Name

    Changemaker Lite uses subdomain routing — app., api., docs., git., and 10+ more subdomains are created automatically. Wildcard DNS (*.yourdomain.org) is the simplest approach.

    Budget ~$10–15/year from any registrar.

  • A Reverse Tunnel or Public IP

    Your server needs to be reachable from the internet. Built-in support for Pangolin — a self-hosted tunnel with SSL, subdomain routing, and access control. The admin dashboard includes a one-click setup wizard.

    Alternatives: Cloudflare Tunnel, a VPS with public IP, or any reverse proxy with SSL.

  • SMTP Email Provider

    Campaign messages, password resets, volunteer invitations, and newsletters all need real email delivery.

    Recommended: Proton Mail (privacy-focused), Mailgun (100/day free), Amazon SES (cheapest at scale), or Brevo (300/day free).

  • A Linux Server

    Any Linux with Docker. Ubuntu 22.04+ LTS recommended. A VPS from DigitalOcean, Hetzner, or Linode works great — or a spare machine on your network if using a tunnel.

Optional services that enhance your deployment

These aren't required but unlock additional features:

Service Purpose Free Tier
Stripe Donations, merchandise, membership plans Free account, pay-as-you-go
Mapbox or Google Maps Better geocoding accuracy for mapping 100K req/mo (Mapbox) or $200/mo credit (Google)
MaxMind GeoLite2 Geographic analytics (visitor locations) Free account
Android phone + Termux SMS campaigns via physical phone gateway Free — no third-party SMS costs
Public IP + UDP 10000 Jitsi self-hosted video conferencing Free (requires open firewall port)

See Prerequisites & External Services for setup details on each.

Quick Install

The fastest path — no source code, no compilation:

curl -fsSL https://gitea.bnkops.com/admin/changemaker.lite/raw/branch/main/scripts/install.sh | bash

This downloads a release tarball (~15 MB — config, compose files, and MkDocs content), runs the 14-step configuration wizard, and pulls pre-built Docker images. First startup takes ~2 minutes.

From Source (Development)

For development or customization:

git clone https://gitea.bnkops.com/admin/changemaker.lite
cd changemaker.lite

bash config.sh

docker compose up -d

Open http://localhost:3000 and sign in with the admin credentials you configured. The API container automatically runs database migrations and seeding on first startup.

Change your password

If you used the wizard's generated password, change it immediately from the admin dashboard.

Configuration Wizard

The config.sh wizard produces a fully populated .env file in 14 steps:

Step What It Does
1. Prerequisites Verifies Docker, Docker Compose, and OpenSSL
2. Environment file Creates .env from .env.example (backs up existing)
3. Domain Sets root domain + 14 derived variables, updates mkdocs.yml
4. Admin credentials Email + password (enforces 12+ chars, mixed case, digit)
5. Secrets Auto-generates 21 unique secrets (JWT, encryption, database, service passwords)
6. Email MailHog (dev) or production SMTP, optionally shared with Listmonk
7. Feature flags 9 toggles: Media, Listmonk, Payments, Chat, Events, Meet, SMS, Docs Comments, Bunker Ops
8. Tunnel Pangolin credentials for secure public access
9. CORS Auto-calculated allowed origins from domain
10. Nginx Renders .conf.template files with domain substitution
11. Homepage Generates services.yaml with 27 service entries
12. Permissions Creates 12 directories with container-friendly permissions
13. Upgrade watcher Installs systemd units for GUI-triggered upgrades (optional, requires sudo)
14. Summary Displays configuration summary + next steps

See Installation for detailed documentation of each step.

Pre-Installation Checklist

Use this to make sure you're ready before running the installer:

  • Docker 24+ and Docker Compose v2 installed
  • OpenSSL installed (for secret generation)
  • Domain name registered and DNS accessible
  • DNS configured — wildcard *.yourdomain.org or individual subdomains pointing to your tunnel/server
  • Tunnel or public IP — Pangolin credentials (API key + Org ID), or server with public IP + SSL
  • SMTP credentials — host, port, username, password from your email provider
  • (Optional) Stripe account for payments
  • (Optional) Mapbox or Google Maps API key for geocoding
  • (Optional) MaxMind account for geographic analytics

Services at a Glance

Changemaker Lite includes 30+ Docker services organized into 8 categories:

Category Services Startup
Core API, Admin, PostgreSQL, Redis, Nginx docker compose up -d v2-postgres redis api admin nginx
Media Fastify media API docker compose up -d media-api
Communication Rocket.Chat, Gancio, Jitsi Meet Individual docker compose up -d commands
Newsletter & Email Listmonk, MailHog docker compose up -d listmonk-app
Developer Tools Code Server, MkDocs, Gitea, NocoDB, n8n Individual docker compose up -d commands
Utilities Mini QR, Excalidraw, Vaultwarden, Homepage docker compose up -d mini-qr excalidraw vaultwarden homepage
Monitoring Prometheus, Grafana, Alertmanager, exporters docker compose --profile monitoring up -d
Infrastructure Newt tunnel, Docker socket proxy Auto-starts with tunnel configuration

See Services Overview for the complete catalog with ports, feature flags, and detailed descriptions.

Next Steps

  • Prerequisites

    Full details on every external service — domain setup, SMTP providers, tunnel options, and optional integrations.

  • Installation

    Detailed setup walkthrough, manual configuration, and the full config wizard reference.

  • Services Overview

    Complete catalog of 30+ containers with ports, feature flags, and descriptions.

  • Environment Variables

    Complete .env reference for every setting.

  • First Steps

    Create your first campaign, add locations to the map, and invite volunteers.

  • Updates & Upgrades

    Keep your installation current with zero-downtime upgrades.

  • Control Panel

    Manage multiple Changemaker Lite instances from a single dashboard.

  • Features at a Glance

    Visual overview of every module — advocacy, mapping, media, payments, and more.