freealberta/mkdocs/docs/getting-started.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.

## 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
- Other Linux distributions with systemd support
- WSL2 on Windows (limited functionality)

!!! 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-50/month.

### Software Prerequisites

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
- **Purpose**: Central hub for all services
- **Features**: Service status, quick links, monitoring

### 💻 Development Tools

- **Code Server**: http://localhost:8888 - VS Code in browser
- **Gitea**: http://localhost:3030 - Git repository management
- **MkDocs Dev**: http://localhost:4000 - Live documentation preview
- **MkDocs Prod**: http://localhost:4001 - Built documentation

### 📧 Communication

- **Listmonk**: http://localhost:9000 - Email campaigns
  - Login with credentials set during configuration

### 🔄 Automation & Data

- **n8n**: http://localhost:5678 - Workflow automation
  - Login with credentials set during configuration
- **NocoDB**: http://localhost:8090 - No-code database

### 🛠️ Interactive Tools

- **Map Viewer**: http://localhost:3000 - Geographic data visualization
- **Mini QR**: 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