---
title: Prerequisites & External Services
description: What you need before installing Changemaker Lite — domain, email, tunnel, and optional third-party accounts.
icon: material/clipboard-check-outline
tags:
  - guide
  - getting-started
  - operator
  - planning
search:
  boost: 2
---

# Prerequisites & External Services

!!! 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`

Before running the installer, gather the external services and accounts listed below. Having these ready makes the configuration wizard a smooth, uninterrupted process.

!!! tip "Don't have these yet?"
    You can still install Changemaker Lite in **development mode** with just Docker — no domain, tunnel, or SMTP required. MailHog captures all emails locally. But for a **production deployment** serving real users, you'll need the items on this page.

---

## Required for Production

### 1. A Domain Name

You need a domain (e.g., `betteredmonton.org`) that you control. Changemaker Lite uses **subdomain routing** — the platform creates subdomains like:

| Subdomain | Purpose |
|-----------|---------|
| `app.yourdomain.org` | Admin dashboard + all public pages |
| `api.yourdomain.org` | Backend API |
| `docs.yourdomain.org` | Documentation site |
| `git.yourdomain.org` | Git hosting (Gitea) |
| `events.yourdomain.org` | Event calendar (Gancio) |
| ... and 10+ more | See [Services Overview](services.md) |

You'll point your domain's DNS to wherever your tunnel or server is hosted. **Wildcard DNS** (`*.yourdomain.org`) is the simplest approach.

**Where to get one:** Any registrar — Namecheap, Cloudflare Registrar, Porkbun, etc. Budget ~$10–15/year.

---

### 2. A Reverse Tunnel or Public IP

Your server needs to be reachable from the internet. Most home/office networks don't have a static public IP, so you need a **reverse tunnel** service that gives your server a stable public address with SSL.

Changemaker Lite has built-in support for **[Pangolin](https://github.com/fosrl/pangolin)** — a self-hosted, open-source tunnel that handles SSL certificates, subdomain routing, and access control automatically. The admin dashboard includes a one-click Pangolin setup wizard.

**What you need:**

- A Pangolin server (or access to a shared one)
- An API key and Organization ID
- Your domain's DNS pointed at the Pangolin server

**Alternatives:** Cloudflare Tunnel (free tier available), a VPS with a public IP, or any reverse proxy with SSL termination.

---

### 3. SMTP Email Provider

Production deployments need a real SMTP server to send emails — campaign messages, password resets, volunteer invitations, and newsletter delivery all depend on it.

**What you need:**

| Setting | Example |
|---------|---------|
| SMTP Host | `smtp.protonmail.ch` |
| SMTP Port | `587` (STARTTLS) or `465` (TLS) |
| SMTP Username | `your-account@provider.com` |
| SMTP Password | Your SMTP password or app-specific password |

**Popular SMTP providers:**

| Provider | Free Tier | Notes |
|----------|-----------|-------|
| **Proton Mail** | Included with paid plan | Privacy-focused, recommended for advocacy |
| **Mailgun** | 100 emails/day (FLEX) | Good deliverability, easy setup |
| **Amazon SES** | 62,000/month (from EC2) | Cheapest at scale, requires verification |
| **Brevo (Sendinblue)** | 300 emails/day | Simple setup, good free tier |
| **Resend** | 100 emails/day | Developer-friendly, modern API |

!!! warning "Shared hosting SMTP"
    Avoid using shared hosting SMTP (GoDaddy, Bluehost, etc.) for campaign emails — they have low sending limits and poor deliverability. Use a dedicated transactional email provider.

---

### 4. A Linux Server

Changemaker Lite runs on any Linux server with Docker. Minimum specs:

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| **RAM** | 2 GB (core only) | 4 GB (full stack) |
| **Disk** | 10 GB | 20+ GB (with media uploads) |
| **CPU** | 1 vCPU | 2+ vCPU |
| **OS** | Any Linux with Docker | Ubuntu 22.04+ LTS |

**Options:** A VPS from DigitalOcean, Hetzner, Linode, or a spare machine on your network. If using a tunnel (Pangolin), the server doesn't need a public IP.

!!! warning "Watch out for host-level services on our ports"
    Changemaker Lite binds ~14 host ports including `9090` (Prometheus), `3000` (admin), `4000` (API), `3030` (Gitea), and `8091` (NocoDB). If another service on your host already uses any of these, `docker compose up -d` will partially succeed and leave the stack in a broken state.

    **Common culprit:** `cockpit.socket` — Ubuntu Server's web admin UI — binds `:9090` by default. Disable it with `sudo systemctl disable --now cockpit.socket` before installing, or reconfigure cockpit to a different port.

    The installer runs `ss -Htln` against the required ports before downloading the tarball and aborts with specific remediation hints if any are bound. You can also run the check manually after install with `bash scripts/validate-env.sh`.

---

## Optional (Enhance Your Deployment)

These are not required but unlock additional platform features:

### Stripe Account (Payments)

For accepting donations, selling merchandise, or managing membership plans. Create a free account at [stripe.com](https://stripe.com). You'll enter your Stripe API keys in the admin settings page (they're stored encrypted in the database).

### Mapbox or Google Maps API Key (Geocoding)

Improves address geocoding accuracy for the mapping module. The platform works without these (using free OpenStreetMap providers), but paid providers are more reliable for bulk operations.

- **Mapbox:** Free tier includes 100,000 requests/month. [Sign up](https://www.mapbox.com/pricing).
- **Google Maps:** Free tier includes $200/month credit (~40,000 requests). [Sign up](https://developers.google.com/maps).

### MaxMind GeoLite2 (Analytics)

For geographic analytics (visitor location tracking). Free account at [maxmind.com](https://www.maxmind.com/en/geolite2/signup). The database auto-downloads at startup when credentials are configured.

### Android Phone with Termux (SMS Campaigns)

The SMS module uses a physical Android phone as an SMS gateway via the Termux app. This is a unique feature for grassroots campaigns that want to send SMS without expensive third-party services.

### Jitsi Meet Requirements (Video Conferencing)

If enabling the self-hosted video conferencing feature:

- Server's **public IP address** (for NAT traversal)
- **UDP port 10000** open in your firewall (for media traffic)

---

## Pre-Installation Checklist

Use this checklist to make sure you're ready:

- [ ] **Domain name** registered and DNS accessible
- [ ] **DNS configured** — wildcard `*.yourdomain.org` or individual subdomain records 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
- [ ] **Linux server** with Docker 24+ and Docker Compose v2 installed
- [ ] **OpenSSL** + **ss** (from `iproute2`) installed (for secret generation + host port check)
- [ ] **Host ports free** — if cockpit is enabled, `sudo systemctl disable --now cockpit.socket`
- [ ] *(Optional)* Stripe account for payments
- [ ] *(Optional)* Mapbox or Google Maps API key for geocoding
- [ ] *(Optional)* MaxMind account for geographic analytics

---

## :material-briefcase-outline:{ .lg } Bunker Operations Can Help { #managed-services }

Setting up infrastructure — domains, tunnels, SMTP, servers — can be the hardest part of self-hosting. **Bunker Operations** offers managed infrastructure for organizations running Changemaker Lite:

<div class="grid cards" markdown>

-   :material-tunnel:{ .lg .middle } **Managed Pangolin Tunnel**

    ---

    Pre-configured tunnel with SSL, wildcard DNS, and automatic subdomain routing. Just plug in your API key and go.

-   :material-email-fast:{ .lg .middle } **SMTP Relay**

    ---

    High-deliverability transactional email with SPF/DKIM/DMARC already configured for your domain.

-   :material-server:{ .lg .middle } **Hosted Servers**

    ---

    Pre-provisioned Linux servers with Docker, monitoring, and automatic backups — ready for a one-command install.

-   :material-wrench:{ .lg .middle } **Setup Assistance**

    ---

    We'll walk you through the full deployment — from domain registration to your first campaign launch.

</div>

!!! quote "Built by organizers, for organizers"
    Bunker Operations exists so campaign teams can focus on **building power** — not wrestling with infrastructure. We provide the plumbing so you can focus on the mission.

    **Get in touch:** [bnkops.com](https://bnkops.com) | `admin@bnkops.ca`

---

## Next Steps

Once you have your prerequisites ready:

- [Installation](installation.md) — run the configuration wizard and start services
- [Environment Variables](environment-variables.md) — complete reference for every `.env` setting
- [Deployment Guide](../deployment/index.md) — production setup with SSL and tunneling
