freealberta/mkdocs/docs/build/index.md

# Getting Started with Digital Liberation 

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.

## Quick Start

### Build Changemkaer-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 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
```

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


## 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 Ubunut" 
    Want some help getting started with a baseline buildout for a Ubunut server? You can use our [BNKops Server Build Script](./build-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

!!! tip "Getting Started on Docker" 
    Want some help getting started with a baseline buildout for a Ubunutu server? You can use our [BNKops Server Build Script](./build-server.md) to roll out a configured server in about 20 mins! 

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  
- **Map Viewer**: [http://localhost:3000](http://localhost:3000) — Geographic data visualization  
- **Mini QR**: [http://localhost:8089](http://localhost:8089) — QR code generator

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