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](installation.md) and changing all default passwords.

## Step 1: Clone the Repository

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

```bash
cp .env.example .env
```

Edit `.env` and set the minimum required variables:

```bash
# 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

```bash
# 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

```bash
# 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](http://localhost:3000)
- **API**: [http://localhost:4000](http://localhost:4000)
- **API Health Check**: [http://localhost:4000/health](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:

```bash
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:

```bash
curl http://localhost:4000/health
```

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

## What's Next?

Now that you have Changemaker Lite running:

1. **[First Login](first-login.md)** - Tour the admin interface
2. **[Environment Configuration](environment.md)** - Customize your setup
3. **[Create Your First Campaign](../user-guides/campaign-manager-guide.md)** - Run an advocacy campaign
4. **[Import Locations](../user-guides/map-organizer-guide.md)** - Set up your map

## Optional: Start Additional Services

### Email Testing (MailHog)

Capture emails in development without sending real messages:

```bash
docker compose up -d mailhog
```

Access at: [http://localhost:8025](http://localhost:8025)

### Data Browser (NocoDB)

Read-only database browser:

```bash
docker compose up -d nocodb-v2
```

Access at: [http://localhost:8091](http://localhost:8091)

### Newsletter Platform (Listmonk)

Email marketing integration:

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

Access at: [http://localhost:9001](http://localhost:9001)

### Monitoring Stack

Prometheus + Grafana + Alertmanager:

```bash
docker compose --profile monitoring up -d
```

Access:
- **Grafana**: [http://localhost:3001](http://localhost:3001) (admin/admin)
- **Prometheus**: [http://localhost:9090](http://localhost:9090)
- **Alertmanager**: [http://localhost:9093](http://localhost:9093)

## Common Issues

### Port Already in Use

If you see errors like `port is already allocated`:

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

# Stop the conflicting service or change ports in .env
```

### Database Connection Failed

```bash
# 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

```bash
# 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 →](../troubleshooting/index.md)

## Stopping Services

```bash
# 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](installation.md)** - Production-ready setup
2. **[Security Checklist](../deployment/security.md)** - Harden your installation
3. **[Backup Strategy](../deployment/backup-restore.md)** - Protect your data
4. **[Tunneling Setup](../deployment/tunneling.md)** - Public access via Pangolin
5. **[Monitoring Configuration](../deployment/monitoring-stack.md)** - Production observability

---

**Congratulations!** You now have Changemaker Lite V2 running locally. Explore the admin interface and check out the [User Guides](../user-guides/index.md) to learn what you can do.