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

### Pre-built Images (Recommended)

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.