freealberta/mkdocs/docs/getting-started.md

# Getting Started

Welcome to Changemaker Lite! This guide will help you get up and running on Ubuntu 24.04 LTS (Noble Numbat) with Docker.

## System Requirements

### Operating System
- **Ubuntu 24.04 LTS (Noble Numbat)** - Recommended and tested
- Other Linux distributions with systemd support
- WSL2 on Windows (limited functionality)

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

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