diff --git a/mkdocs/docs/getting-started.md b/mkdocs/docs/getting-started.md index ef456d9..d8b1138 100644 --- a/mkdocs/docs/getting-started.md +++ b/mkdocs/docs/getting-started.md @@ -1,15 +1,45 @@ # Getting Started -Welcome to Changemaker Lite! This guide will help you get up and running quickly. +Welcome to Changemaker Lite! This guide will help you get up and running on Ubuntu 24.04 LTS (Noble Numbat) with Docker. -## Prerequisites +## System Requirements -Before starting, ensure you have: +### Operating System +- **Ubuntu 24.04 LTS (Noble Numbat)** - Recommended and tested +- Other Linux distributions with systemd support +- WSL2 on Windows (limited functionality) -- [Docker](https://docs.docker.com/get-docker/) installed -- [Docker Compose](https://docs.docker.com/compose/install/) installed -- Git for cloning the repository -- Basic familiarity with terminal/command line +### 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 @@ -20,19 +50,34 @@ git clone https://gitea.bnkops.com/admin/Changemaker.git cd changemaker.lite ``` -### 2. Configuration +### 2. Run Configuration Wizard -Run the configuration script to set up environment variables: +The `config.sh` script will guide you through the initial setup: ```bash ./config.sh ``` -This creates a `.env` file with default settings. You can edit this file to customize: -- Service ports -- Database credentials -- User/group IDs -- Domain settings +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 @@ -42,190 +87,272 @@ Launch all services with Docker Compose: docker compose up -d ``` -Wait a few minutes for all services to start, especially on first run as Docker images need to be downloaded. +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 services are running: +Check that all services are running: ```bash docker compose ps ``` -All services should show as "Up" status. +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 -## First Steps +## Local Access -### Access the Dashboard +Once services are running, access them locally: -Start with the **Homepage Dashboard**: http://localhost:3010 -- Central hub for all services -- Live status monitoring -- Quick access to all applications +### 🏠 Homepage Dashboard +- **URL**: http://localhost:3010 +- **Purpose**: Central hub for all services +- **Features**: Service status, quick links, monitoring -### Access Documentation +### 💻 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 -1. **Development Server**: http://localhost:4000 - - Live preview with auto-reload - - Used while writing documentation +### 📧 Communication +- **Listmonk**: http://localhost:9000 - Email campaigns + - Login with credentials set during configuration -2. **Production Server**: http://localhost:4001 - - Serves built static site - - Optimized for performance +### 🔄 Automation & Data +- **n8n**: http://localhost:5678 - Workflow automation + - Login with credentials set during configuration +- **NocoDB**: http://localhost:8090 - No-code database -### Start Coding +### 🛠️ Interactive Tools +- **Map Viewer**: http://localhost:3000 - Geographic data visualization +- **Mini QR**: http://localhost:8089 - QR code generator -1. Open **Code Server**: http://localhost:8888 -2. Navigate to `/home/coder/mkdocs/` workspace -3. Edit documentation files in `docs/` directory -4. See changes instantly in development server +## Production Deployment -### Set Up Email Campaigns +### Deploy with Cloudflare Tunnels -1. Access **Listmonk**: http://localhost:9000 -2. Log in with admin credentials (set in config) -3. Configure SMTP settings -4. Create your first mailing list +For secure public access, use the production deployment script: -### Create Workflows +```bash +./start-production.sh +``` -1. Open **n8n**: http://localhost:5678 -2. Log in with admin credentials -3. Create your first workflow -4. Connect different services together +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 -### Manage Data with NocoDB +### What Happens During Production Setup -1. Access **NocoDB**: http://localhost:8090 -2. Complete the initial setup -3. Create your first project -4. Import data or create new tables +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 -### Access All Services via Homepage +### Production URLs -1. Open **Homepage**: http://localhost:3010 -2. View all services in one dashboard -3. Monitor service status -4. Quick access to all applications +After successful deployment, services will be available at: -## Configuration Details +**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 -# Service Ports +# 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 -LISTMONK_PORT=9000 N8N_PORT=5678 NOCODB_PORT=8090 +GITEA_WEB_PORT=3030 +GITEA_SSH_PORT=2222 +MAP_PORT=3000 +MINI_QR_PORT=8089 -# Database -POSTGRES_USER=listmonk -POSTGRES_PASSWORD=your_secure_password -POSTGRES_DB=listmonk - -# User/Group IDs (match your system) -USER_ID=1000 -GROUP_ID=1000 +# Cloudflare (for production) +CF_API_TOKEN=your_token +CF_ZONE_ID=your_zone_id +CF_ACCOUNT_ID=your_account_id ``` -### Volume Mounts +### Reconfigure Services -Important directories: +To update configuration: -- `./mkdocs/`: Documentation source files -- `./configs/`: Service configurations -- `./assets/`: Shared assets and uploads -- Docker volumes for persistent data +```bash +# Re-run configuration wizard +./config.sh + +# Restart services +docker compose down && docker compose up -d +``` ## Common Tasks -### Writing Documentation - -1. Edit files in `mkdocs/docs/` using Code Server -2. Preview changes at http://localhost:4000 -3. Build static site: `docker exec mkdocs-changemaker mkdocs build` -4. View built site at http://localhost:4001 - -### Managing Services +### Service Management ```bash -# View logs -docker compose logs [service-name] +# View all services +docker compose ps -# Restart service +# 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 -# Update services -docker compose pull && docker compose up -d +# Stop and remove all data (CAUTION!) +docker compose down -v ``` -### Backup Important Data +### Backup Data -- Export n8n workflows -- Backup PostgreSQL database -- Version control your documentation files -- Save service configurations +```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 ports are already in use, edit `.env` file: +If services fail to start due to port conflicts: -```env -CODE_SERVER_PORT=8889 # Change from 8888 -MKDOCS_PORT=4002 # Change from 4000 +1. Check which ports are in use: +```bash +sudo ss -tulpn | grep LISTEN ``` -Then restart: `docker compose down && docker compose up -d` +2. Re-run configuration to get new ports: +```bash +./config.sh +``` + +3. Or manually edit `.env` file and change conflicting ports ### Permission Issues -Ensure correct user/group IDs in `.env`: +Fix permission problems: ```bash -# Get your user ID -id -u +# Get your user and group IDs +id -u # User ID +id -g # Group ID -# Get your group ID -id -g +# Update .env file with correct IDs +USER_ID=1000 +GROUP_ID=1000 + +# Restart services +docker compose down && docker compose up -d ``` -Update `.env` with these values and restart services. - ### Service Won't Start -Check logs for specific errors: +Debug service issues: ```bash -docker compose logs [service-name] +# Check detailed logs +docker compose logs [service-name] --tail 50 + +# Check container status +docker ps -a + +# Inspect container +docker inspect [container-name] ``` -Common issues: -- Port conflicts -- Permission problems -- Missing environment variables -- Network connectivity +### 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 -- Explore the [Services](services/index.md) documentation -- Set up your first [n8n workflow](services/n8n.md) -- Configure [Listmonk](services/listmonk.md) for email campaigns -- Customize your [MkDocs](services/mkdocs.md) theme and content +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 service-specific documentation -- Review Docker container logs -- Verify environment configuration -- Test network connectivity between services +- 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 diff --git a/mkdocs/docs/index.md b/mkdocs/docs/index.md index d802c02..7ad2ac6 100644 --- a/mkdocs/docs/index.md +++ b/mkdocs/docs/index.md @@ -1,6 +1,6 @@ # Welcome to Changemaker Lite -A streamlined, self-hosted platform for documentation and development. +A streamlined, self-hosted platform for documentation, development, and digital activism. ## Quick Start @@ -16,45 +16,87 @@ cd changemaker.lite # Start all services docker compose up -d + +# For production deployment with Cloudflare tunnels +./start-production.sh ``` ## Services Changemaker Lite includes these essential services: -- **[Homepage](services/homepage.md)** (Port 3010) - Service dashboard and monitoring +### Core Services +- **[Homepage](services/homepage.md)** (Port 3010) - Central dashboard and service monitoring - **[Code Server](services/code-server.md)** (Port 8888) - VS Code in your browser - **[MkDocs](services/mkdocs.md)** (Port 4000) - Documentation with live preview -- **[Static Server](services/static-server.md)** (Port 4001) - Built site hosting -- **[Waypoint Editor](services/waypoint-editor.md)** (Port 3020) - Visual page editor -- **[Listmonk](services/listmonk.md)** (Port 9000) - Newsletter management -- **[PostgreSQL](services/postgresql.md)** (Port 5432) - Database backend -- **[n8n](services/n8n.md)** (Port 5678) - Workflow automation +- **[Static Server](services/static-server.md)** (Port 4001) - Production documentation site + +### Communication & Automation +- **[Listmonk](services/listmonk.md)** (Port 9000) - Newsletter and email campaign management +- **[n8n](services/n8n.md)** (Port 5678) - Workflow automation platform + +### Data & Development - **[NocoDB](services/nocodb.md)** (Port 8090) - No-code database platform +- **[PostgreSQL](services/postgresql.md)** (Port 5432) - Database backend for Listmonk +- **[Gitea](services/gitea.md)** (Port 3030) - Self-hosted Git service + +### Interactive Tools +- **[Map Viewer](services/map.md)** (Port 3000) - Interactive map with NocoDB integration +- **[Mini QR](services/mini-qr.md)** (Port 8089) - QR code generator ## Getting Started -1. **Documentation**: Start writing in [Code Server](http://localhost:8888) -2. **Preview**: See live changes at [MkDocs](http://localhost:4000) -3. **Production**: View built site at [Static Server](http://localhost:4001) -4. **Email**: Set up campaigns with [Listmonk](http://localhost:9000) -5. **Automation**: Create workflows in [n8n](http://localhost:5678) +1. **Setup**: Run `./config.sh` to configure your environment +2. **Launch**: Start services with `docker compose up -d` +3. **Dashboard**: Access the Homepage at [http://localhost:3010](http://localhost:3010) +4. **Production**: Deploy with Cloudflare tunnels using `./start-production.sh` ## Project Structure ``` changemaker.lite/ ├── docker-compose.yml # Service definitions -├── config.sh # Setup script +├── config.sh # Configuration wizard +├── start-production.sh # Production deployment script ├── mkdocs/ # Documentation source │ ├── docs/ # Markdown files -│ └── mkdocs.yml # Configuration +│ └── mkdocs.yml # MkDocs configuration ├── configs/ # Service configurations +│ ├── homepage/ # Homepage dashboard config +│ ├── code-server/ # VS Code settings +│ └── cloudflare/ # Tunnel configurations +├── map/ # Map application +│ ├── app/ # Node.js application +│ ├── Dockerfile # Container definition +│ └── .env # Map configuration └── assets/ # Shared assets + ├── images/ # Image files + ├── icons/ # Service icons + └── uploads/ # Listmonk uploads ``` +## Key Features + +- 🐳 **Fully Containerized** - All services run in Docker containers +- 🔒 **Production Ready** - Built-in Cloudflare tunnel support for secure access +- 📦 **All-in-One** - Everything you need for documentation, development, and campaigns +- 🗺️ **Geographic Data** - Interactive maps with real-time location tracking +- 📧 **Email Campaigns** - Professional newsletter management +- 🔄 **Automation** - Connect services and automate workflows +- 💾 **Version Control** - Self-hosted Git repository +- 🎯 **No-Code Database** - Build applications without programming + +## System Requirements + +- **OS**: Ubuntu 24.04 LTS (Noble Numbat) or compatible Linux distribution +- **Docker**: Version 24.0+ with Docker Compose v2 +- **Memory**: Minimum 4GB RAM (8GB recommended) +- **Storage**: 20GB+ available disk space +- **Network**: Internet connection for initial setup + ## Learn More -- [Services Overview](services/index.md) - Detailed service documentation +- [Getting Started](getting-started.md) - Detailed installation guide +- [Services Overview](services/index.md) - Deep dive into each service - [Blog](blog/index.md) - Updates and tutorials -- [GitHub Repository](https://gitea.bnkops.com/admin/Changemaker) - Source code and issues +- [GitHub Repository](https://gitea.bnkops.com/admin/Changemaker) - Source code