--- title: Getting Started description: Everything you need to deploy Changemaker Lite — from prerequisites to your first login. icon: material/rocket-launch tags: - guide - getting-started - operator - planning search: boost: 2 --- # 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. !!! tip "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](https://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. ### :material-laptop:{ .lg } Development (Local Testing) All you need is Docker — no domain, tunnel, or SMTP required:
- :material-docker:{ .lg .middle } **Docker 24+ & Compose v2** --- The only hard requirement. All 30+ services run as containers. - :material-lock:{ .lg .middle } **OpenSSL** --- Used by the config wizard to auto-generate 21 secrets (JWT, encryption keys, passwords). - :material-memory:{ .lg .middle } **2 GB RAM / 10 GB Disk** --- Minimum for core services. 4 GB recommended if enabling media, chat, or monitoring.
!!! tip "MailHog captures all emails locally" In dev mode, every outbound email is caught by MailHog at `http://localhost:8025` — no SMTP provider needed. ### :material-server:{ .lg } Production Deployment For a deployment that serves real users, you'll also need:
- :material-web:{ .lg .middle } **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. - :material-tunnel:{ .lg .middle } **A Reverse Tunnel or Public IP** --- Your server needs to be reachable from the internet. Built-in support for **[Pangolin](https://github.com/fosrl/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.* - :material-email-fast:{ .lg .middle } **SMTP Email Provider** --- Campaign messages, password resets, volunteer invitations, and newsletters all need real email delivery. Recommended: **[Proton Mail](https://proton.me/mail)** (privacy-focused), **[Mailgun](https://www.mailgun.com)** (100/day free), **[Amazon SES](https://aws.amazon.com/ses/)** (cheapest at scale), or **[Brevo](https://www.brevo.com)** (300/day free). - :material-linux:{ .lg .middle } **A Linux Server** --- Any Linux with Docker. Ubuntu 22.04+ LTS recommended. A VPS from [DigitalOcean](https://www.digitalocean.com), [Hetzner](https://www.hetzner.com), or [Linode](https://www.linode.com) works great — or a spare machine on your network if using a tunnel.
??? info "Optional services that enhance your deployment" These aren't required but unlock additional features: | Service | Purpose | Free Tier | |---------|---------|-----------| | **[Stripe](https://stripe.com)** | Donations, merchandise, membership plans | Free account, pay-as-you-go | | **[Mapbox](https://www.mapbox.com/pricing)** or **[Google Maps](https://developers.google.com/maps)** | Better geocoding accuracy for mapping | 100K req/mo (Mapbox) or $200/mo credit (Google) | | **[MaxMind GeoLite2](https://www.maxmind.com/en/geolite2/signup)** | Geographic analytics (visitor locations) | Free account | | **[Android phone + Termux](https://termux.dev)** | 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](prerequisites.md) for setup details on each. --- ## :material-lightning-bolt: Quick Install ### Pre-built Images (Recommended) The fastest path — no source code, no compilation: ```bash 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: ```bash git clone https://gitea.bnkops.com/admin/changemaker.lite cd changemaker.lite ``` ```bash bash config.sh ``` ```bash 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. !!! warning "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](installation.md) 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](services.md) for the complete catalog with ports, feature flags, and detailed descriptions. --- ## Next Steps
- :material-clipboard-check-outline:{ .lg .middle } **[Prerequisites](prerequisites.md)** --- Full details on every external service — domain setup, SMTP providers, tunnel options, and optional integrations. - :material-download:{ .lg .middle } **[Installation](installation.md)** --- Detailed setup walkthrough, manual configuration, and the full config wizard reference. - :material-view-grid:{ .lg .middle } **[Services Overview](services.md)** --- Complete catalog of 30+ containers with ports, feature flags, and descriptions. - :material-cog:{ .lg .middle } **[Environment Variables](environment-variables.md)** --- Complete `.env` reference for every setting. - :material-flag-checkered:{ .lg .middle } **[First Steps](first-steps.md)** --- Create your first campaign, add locations to the map, and invite volunteers. - :material-arrow-up-circle:{ .lg .middle } **[Updates & Upgrades](upgrades.md)** --- Keep your installation current with zero-downtime upgrades. - :material-monitor-dashboard:{ .lg .middle } **[Control Panel](control-panel.md)** --- Manage multiple Changemaker Lite instances from a single dashboard. - :material-star-shooting:{ .lg .middle } **[Features at a Glance](features.md)** --- Visual overview of every module — advocacy, mapping, media, payments, and more.