changemaker.lite/mkdocs/docs/v2/getting-started/quick-start.md

Quick Start Guide

Get Changemaker Lite V2 running in 5 minutes with this streamlined guide.

!!! warning "For Evaluation Only" This quick start uses default credentials and minimal configuration. Do not use in production without following the Full Installation Guide and changing all default passwords.

Step 1: Clone the Repository

git clone <repo-url> changemaker.lite
cd changemaker.lite
git checkout v2

!!! tip If you're evaluating locally, you can skip the domain configuration and use localhost URLs.

Step 2: Create Environment File

cp .env.example .env

Edit .env and set the minimum required variables:

# Database
V2_POSTGRES_PASSWORD=your_secure_password_here

# Redis
REDIS_PASSWORD=another_secure_password

# JWT Secrets (generate with: openssl rand -hex 32)
JWT_ACCESS_SECRET=<your-access-secret>
JWT_REFRESH_SECRET=<your-refresh-secret>

# Encryption Key (must differ from JWT secrets)
ENCRYPTION_KEY=<your-encryption-key>

# Email (use test mode for evaluation)
EMAIL_TEST_MODE=true

!!! tip "Generate Secure Secrets" bash echo "JWT_ACCESS_SECRET=$(openssl rand -hex 32)" echo "JWT_REFRESH_SECRET=$(openssl rand -hex 32)" echo "ENCRYPTION_KEY=$(openssl rand -hex 32)"

Step 3: Start Core Services

# Start database and cache
docker compose up -d v2-postgres redis

# Wait for database to be ready (about 10 seconds)
sleep 10

# Start API and admin
docker compose up -d api admin nginx

Step 4: Run Database Migrations

# Run Prisma migrations
docker compose exec api npx prisma migrate deploy

# Seed initial data (creates admin user)
docker compose exec api npx prisma db seed

This creates:

• Admin user: admin@example.com / Admin123!
• Site settings: Default configuration
• Page blocks: Landing page components

Step 5: Access the Platform

Open your browser and navigate to:

• Admin Interface: http://localhost:3000
• API: http://localhost:4000
• API Health Check: http://localhost:4000/health

Login with:

• Email: admin@example.com
• Password: Admin123!

!!! danger "Change Default Credentials" Immediately change the default admin password:

1. Navigate to **Settings** in the sidebar
2. Click your profile
3. Change password to something secure (12+ chars, mixed case, numbers)

Step 6: Verify Installation

Check that all services are running:

docker compose ps

You should see:

• v2-postgres - Database (port 5433)
• redis-changemaker - Cache (port 6379)
• api - Express API (port 4000)
• admin - React admin (port 3000)
• nginx - Reverse proxy (port 80)

Test the API:

curl http://localhost:4000/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2026-02-11T18:00:00.000Z"
}

What's Next?

Now that you have Changemaker Lite running:

1. First Login - Tour the admin interface
2. Environment Configuration - Customize your setup
3. Create Your First Campaign - Run an advocacy campaign
4. Import Locations - Set up your map

Optional: Start Additional Services

Email Testing (MailHog)

Capture emails in development without sending real messages:

docker compose up -d mailhog

Access at: http://localhost:8025

Data Browser (NocoDB)

Read-only database browser:

docker compose up -d nocodb-v2

Access at: http://localhost:8091

Newsletter Platform (Listmonk)

Email marketing integration:

docker compose up -d listmonk-postgres listmonk listmonk-init

Access at: http://localhost:9001

Monitoring Stack

Prometheus + Grafana + Alertmanager:

docker compose --profile monitoring up -d

Access:

• Grafana: http://localhost:3001 (admin/admin)
• Prometheus: http://localhost:9090
• Alertmanager: http://localhost:9093

Common Issues

Port Already in Use

If you see errors like port is already allocated:

# Check what's using the port
sudo lsof -i :3000

# Stop the conflicting service or change ports in .env

Database Connection Failed

# Check if PostgreSQL is running
docker compose ps v2-postgres

# View logs
docker compose logs v2-postgres

# Restart database
docker compose restart v2-postgres

API Won't Start

# View API logs
docker compose logs api

# Common fix: rebuild the container
docker compose build api
docker compose up -d api

See full troubleshooting guide →

Stopping Services

# Stop all services
docker compose down

# Stop and remove volumes (WARNING: deletes all data)
docker compose down -v

Next Steps for Production

This quick start is for evaluation only. Before production deployment:

1. Full Installation Guide - Production-ready setup
2. Security Checklist - Harden your installation
3. Backup Strategy - Protect your data
4. Tunneling Setup - Public access via Pangolin
5. Monitoring Configuration - Production observability

---

Congratulations! You now have Changemaker Lite V2 running locally. Explore the admin interface and check out the User Guides to learn what you can do.