freealberta/mkdocs/docs/build/index.md

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:

• 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!)

Quick Start

Build Changemaker-Lite

# 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

# 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 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 as a drop in replacement.

For secure public access, use the production deployment script:

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

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

!!! tip "New to Linux?" Consider Linux Mint - 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 to roll out a configured server in about 20 mins!

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.lite
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

• Mini QR: 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

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