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+)

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

# Verify Docker Compose v2 is installed
docker compose version

3. Essential Tools

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

Installation

1. Clone Repository

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:

./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:

docker compose up -d

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

# Watch container status
docker compose ps

# View logs
docker compose logs -f

4. Verify Installation

Check that all services are running:

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:

./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:

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

# Re-run configuration wizard
./config.sh

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

Common Tasks

Service Management

# 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

# 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

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

sudo ss -tulpn | grep LISTEN

2. Re-run configuration to get new ports:

./config.sh

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

Permission Issues

Fix permission problems:

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

# 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

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