# Getting Started

Welcome to Changemaker-Lite! You're about to reclaim your digital sovereignty and stop feeding your secrets to corporations. This guide will help you set up your own political infrastructure that you actually own and control.

This documentation is broken into a few sections, which you can see in the navigation bar to the left: 

- **Build:** Instructions on how to build the cm-lite on your own hardware 
- **Services:** Overview of all the services that are installed when you install cm-lite
- **Configuration:** Information on how to configure all the services that you install in cm-lite
- **Manuals:** Manuals on how to use the applications inside cm-lite (with videos!)

Of course, everything is also searachable, so if you want to find something specific, just use the search bar at the top right.

If you come across anything that is unclear, please open an issue in the [Git Repository](https://gitea.bnkops.com/admin/changemaker.lite), reach out to us at [admin@thebunkerops.ca](mailto:admin@thebunkerops.ca), or edit it yourself by clicking the pencil icon at the top right of each page.

## Quick Start

### Build Changemaker-Lite

```bash
# Clone the repository
git clone https://gitea.bnkops.com/admin/changemaker.lite
cd changemaker.lite
```

!!! warning "Cloudflare Credentials"
    The config.sh script will ask you for your optional Cloudflare credentials to get started. You can find more information on how to find this in the [Cloudlflare Configuration](../config/cloudflare-config.md)


```
# Configure environment (creates .env file)
./config.sh
```

```
# Start all services
docker compose up -d
```

### Optional - Site Builld 

If you want to have your site prepared for launch, you can now proceed with reseting the site build. See [Build Site](../build/site.md) for more detials. 

### Deploy

!!! note "Cloudflare" 
    Right now, we suggest deploying using Cloudflare for simplicity and protections against 99% of surface level attacks to digital infrastructure. If you want to avoid using this service, we recommend checking out [Pagolin](https://github.com/fosrl/pangolin) as a drop in replacement. 

For secure public access, use the production deployment script:

```bash
./start-production.sh
```

### Map 

Map is the canvassing application that is custom view of nocodb data. Map is best built **after production deployment** to reduce duplicate build efforts.

Instructions on how to build the map are available in the [map manual](../build/map.md) in the build directory.

#### Quick Start for Map
Get your NocoDB API token and URL, update the .env file in the map directory, and then run:

```
cd map
chmod +x build-nocodb.sh # builds the nocodb tables
./build-nocodb.sh
```
Copy the urls of the newly created nocodb views and update the .env file in the map directory with them, and then run:

```
cd map
docker compose up -d
```

You Map instance will be available at [http://localhost:3000](http://localhost:3000) or on the domain you set up during production deployment.

## Why Changemaker Lite?

Before we dive into the technical setup, let's be clear about what you're doing here:

!!! quote "The Reality"
    **If you do politics, who is reading your secrets?** Every corporate platform you use is extracting your power, selling your data, and building profiles on your community. It's time to break free.

### What You're Getting

- **Data Sovereignty**: Your data stays on your servers
- **Cost Savings**: $50/month instead of $2,000+/month for corporate solutions  
- **Community Control**: Technology that serves movements, not shareholders
- **Trans Liberation**: Tools built with radical politics and care

### What You're Leaving Behind

- ❌ Corporate surveillance and data extraction
- ❌ Escalating subscription fees and vendor lock-in
- ❌ Algorithmic manipulation of your community
- ❌ Terms of service that can silence you anytime

---

## System Requirements

### Operating System

- **Ubuntu 24.04 LTS (Noble Numbat)** - Recommended and tested

!!! note "Getting Started on Ubuntu" 
    Want some help getting started with a baseline buildout for a Ubuntu server? You can use our [BNKops Server Build Script](./server.md)

- Other Linux distributions with systemd support
- WSL2 on Windows (limited functionality)
- Mac OS

!!! tip "New to Linux?"
    Consider [Linux Mint](https://www.linuxmint.com/) - it looks like Windows but opens the door to true digital freedom.

### Hardware Requirements

- **CPU**: 2+ cores (4+ recommended)
- **RAM**: 4GB minimum (8GB recommended)  
- **Storage**: 20GB+ available disk space
- **Network**: Stable internet connection

!!! info "Cloud Hosting"
    You can run this on a VPS from providers like Hetzner, DigitalOcean, or Linode for ~$20/month.

### Software Prerequisites

Ensure the following software is installed on your system. The [BNKops Server Build Script](./server.md) can help set these up if you're on Ubuntu. 

1. **Docker Engine** (24.0+)

```bash
# Install Docker
curl -fsSL https://get.docker.com | sudo sh

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in for group changes to take effect
```

2. **Docker Compose** (v2.20+)

```bash
# Verify Docker Compose v2 is installed
docker compose version
```

3. **Essential Tools**

```bash
# Install required packages
sudo apt update
sudo apt install -y git curl jq openssl
```

## Installation

### 1. Clone Repository

```bash
git clone https://gitea.bnkops.com/admin/changemaker.lite
cd changemaker.lite
```

### 2. Run Configuration Wizard

The `config.sh` script will guide you through the initial setup:

```bash
./config.sh
```

This wizard will:

- ✅ Create a `.env` file with secure defaults
- ✅ Scan for available ports to avoid conflicts
- ✅ Set up your domain configuration
- ✅ Generate secure passwords for databases
- ✅ Configure Cloudflare credentials (optional)
- ✅ Update all configuration files with your settings

#### Configuration Options

During setup, you'll be prompted for:

1. **Domain Name**: Your primary domain (e.g., `example.com`)
2. **Cloudflare Settings** (optional):
   - API Token
   - Zone ID
   - Account ID
3. **Admin Credentials**:
   - Listmonk admin email and password
   - n8n admin email and password

### 3. Start Services

Launch all services with Docker Compose:

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

Wait for services to initialize (first run may take 5-10 minutes):

```bash
# Watch container status
docker compose ps

# View logs
docker compose logs -f
```

### 4. Verify Installation

Check that all services are running:

```bash
docker compose ps
```

Expected output should show all services as "Up":

- code-server-changemaker
- listmonk_app
- listmonk_db
- mkdocs-changemaker
- mkdocs-site-server-changemaker
- n8n-changemaker
- nocodb
- root_db
- homepage-changemaker
- gitea_changemaker
- gitea_mysql_changemaker
- mini-qr

## Local Access

Once services are running, access them locally:

### 🏠 Homepage Dashboard  
- **URL**: [http://localhost:3010](http://localhost:3010)  
- **Purpose**: Central hub for all services  
- **Features**: Service status, quick links, monitoring

### 💻 Development Tools  
- **Code Server**: [http://localhost:8888](http://localhost:8888) — VS Code in browser  
- **Gitea**: [http://localhost:3030](http://localhost:3030) — Git repository management  
- **MkDocs Dev**: [http://localhost:4000](http://localhost:4000) — Live documentation preview  
- **MkDocs Prod**: [http://localhost:4001](http://localhost:4001) — Built documentation

### 📧 Communication  
- **Listmonk**: [http://localhost:9000](http://localhost:9000) — Email campaigns  
    _Login with credentials set during configuration_

### 🔄 Automation & Data  
- **n8n**: [http://localhost:5678](http://localhost:5678) — Workflow automation  
    _Login with credentials set during configuration_  
- **NocoDB**: [http://localhost:8090](http://localhost:8090) — No-code database

### 🛠️ Interactive Tools  
- **Mini QR**: [http://localhost:8089](http://localhost:8089) — QR code generator

## Map 

!!! warning "Map" 
    Map is the canvassing application that is custom view of nocodb data. Map is best built **after production deployment** to reduce duplicate build efforts. 

### [Map Manual](map.md)

## Production Deployment

### Deploy with Cloudflare Tunnels

For secure public access, use the production deployment script:

```bash
./start-production.sh
```

This script will:

1. Install and configure `cloudflared`
2. Create a Cloudflare tunnel
3. Set up DNS records automatically
4. Configure access policies
5. Create a systemd service for persistence

### What Happens During Production Setup

1. **Cloudflare Authentication**: Browser-based login to Cloudflare
2. **Tunnel Creation**: Secure tunnel named `changemaker-lite`
3. **DNS Configuration**: Automatic CNAME records for all services
4. **Access Policies**: Email-based authentication for sensitive services
5. **Service Installation**: Systemd service for automatic startup

### Production URLs

After successful deployment, services will be available at:

**Public Services**:

- `https://yourdomain.com` - Main documentation site
- `https://listmonk.yourdomain.com` - Email campaigns
- `https://docs.yourdomain.com` - Documentation preview
- `https://n8n.yourdomain.com` - Automation platform
- `https://db.yourdomain.com` - NocoDB
- `https://git.yourdomain.com` - Gitea
- `https://map.yourdomain.com` - Map viewer
- `https://qr.yourdomain.com` - QR generator

**Protected Services** (require authentication):

- `https://homepage.yourdomain.com` - Dashboard
- `https://code.yourdomain.com` - Code Server

## Configuration Management

### Environment Variables

Key settings in `.env` file:

```env
# Domain Configuration
DOMAIN=yourdomain.com
BASE_DOMAIN=https://yourdomain.com

# Service Ports (automatically assigned to avoid conflicts)
HOMEPAGE_PORT=3010
CODE_SERVER_PORT=8888
LISTMONK_PORT=9000
MKDOCS_PORT=4000
MKDOCS_SITE_SERVER_PORT=4001
N8N_PORT=5678
NOCODB_PORT=8090
GITEA_WEB_PORT=3030
GITEA_SSH_PORT=2222
MAP_PORT=3000
MINI_QR_PORT=8089

# Cloudflare (for production)
CF_API_TOKEN=your_token
CF_ZONE_ID=your_zone_id
CF_ACCOUNT_ID=your_account_id
```

### Reconfigure Services

To update configuration:

```bash
# Re-run configuration wizard
./config.sh

# Restart services
docker compose down && docker compose up -d
```

## Common Tasks

### Service Management

```bash
# View all services
docker compose ps

# View logs for specific service
docker compose logs -f [service-name]

# Restart a service
docker compose restart [service-name]

# Stop all services
docker compose down

# Stop and remove all data (CAUTION!)
docker compose down -v
```

### Backup Data

```bash
# Backup all volumes
docker run --rm -v changemaker_listmonk-data:/data -v $(pwd):/backup alpine tar czf /backup/listmonk-backup.tar.gz -C /data .

# Backup configuration
tar czf configs-backup.tar.gz configs/

# Backup documentation
tar czf docs-backup.tar.gz mkdocs/docs/
```

### Update Services

```bash
# Pull latest images
docker compose pull

# Recreate containers with new images
docker compose up -d
```

## Troubleshooting

### Port Conflicts

If services fail to start due to port conflicts:

1. Check which ports are in use:

```bash
sudo ss -tulpn | grep LISTEN
```

2. Re-run configuration to get new ports:

```bash
./config.sh
```

3. Or manually edit `.env` file and change conflicting ports

### Permission Issues

Fix permission problems:

```bash
# Get your user and group IDs
id -u  # User ID
id -g  # Group ID

# Update .env file with correct IDs
USER_ID=1000
GROUP_ID=1000

# Restart services
docker compose down && docker compose up -d
```

### Service Won't Start

Debug service issues:

```bash
# Check detailed logs
docker compose logs [service-name] --tail 50

# Check container status
docker ps -a

# Inspect container
docker inspect [container-name]
```

### Cloudflare Tunnel Issues

```bash
# Check tunnel service status
sudo systemctl status cloudflared-changemaker

# View tunnel logs
sudo journalctl -u cloudflared-changemaker -f

# Restart tunnel
sudo systemctl restart cloudflared-changemaker
```

## Next Steps

Now that your Changemaker Lite instance is running:

1. **Set up Listmonk** - Configure SMTP and create your first campaign
2. **Create workflows** - Build automations in n8n
3. **Import data** - Set up your NocoDB databases
4. **Configure map** - Add location data for the map viewer
5. **Write documentation** - Start creating content in MkDocs
6. **Set up Git** - Initialize repositories in Gitea

## Getting Help

- Check the [Services](../services/index.md) documentation for detailed guides
- Review container logs for specific error messages
- Ensure all prerequisites are properly installed
- Verify your domain DNS settings for production deployment