admin/freealberta
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

commit

Browse Source
This commit is contained in:
admin 2025-06-29 22:55:51 -06:00
parent c658f4bd00
commit 7a279ee66d
2 changed files with 302 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

361
mkdocs/docs/getting-started.md
View File

@ -1,15 +1,45 @@
# Getting Started # 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 ### Hardware Requirements
- [Docker Compose](https://docs.docker.com/compose/install/) installed - **CPU**: 2+ cores (4+ recommended)
- Git for cloning the repository - **RAM**: 4GB minimum (8GB recommended)
- Basic familiarity with terminal/command line - **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 ## Installation
@ -20,19 +50,34 @@ git clone https://gitea.bnkops.com/admin/Changemaker.git
cd changemaker.lite 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 ```bash
./config.sh ./config.sh
``` ```
This creates a `.env` file with default settings. You can edit this file to customize: This wizard will:
- Service ports - ✅ Create a `.env` file with secure defaults
- Database credentials - ✅ Scan for available ports to avoid conflicts
- User/group IDs - ✅ Set up your domain configuration
- Domain settings - ✅ 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 ### 3. Start Services
@ -42,190 +87,272 @@ Launch all services with Docker Compose:
docker compose up -d 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 ### 4. Verify Installation
Check that services are running: Check that all services are running:
```bash ```bash
docker compose ps 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 ### 🏠 Homepage Dashboard
- Central hub for all services - **URL**: http://localhost:3010
- Live status monitoring - **Purpose**: Central hub for all services
- Quick access to all applications - **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 ### 📧 Communication
- Live preview with auto-reload - **Listmonk**: http://localhost:9000 - Email campaigns
- Used while writing documentation - Login with credentials set during configuration
2. **Production Server**: http://localhost:4001 ### 🔄 Automation & Data
- Serves built static site - **n8n**: http://localhost:5678 - Workflow automation
- Optimized for performance - 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 ## Production Deployment
2. Navigate to `/home/coder/mkdocs/` workspace
3. Edit documentation files in `docs/` directory
4. See changes instantly in development server
### Set Up Email Campaigns ### Deploy with Cloudflare Tunnels
1. Access **Listmonk**: http://localhost:9000 For secure public access, use the production deployment script:
2. Log in with admin credentials (set in config)
3. Configure SMTP settings
4. Create your first mailing list
### Create Workflows ```bash
./start-production.sh
```
1. Open **n8n**: http://localhost:5678 This script will:
2. Log in with admin credentials 1. Install and configure `cloudflared`
3. Create your first workflow 2. Create a Cloudflare tunnel
4. Connect different services together 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 1. **Cloudflare Authentication**: Browser-based login to Cloudflare
2. Complete the initial setup 2. **Tunnel Creation**: Secure tunnel named `changemaker-lite`
3. Create your first project 3. **DNS Configuration**: Automatic CNAME records for all services
4. Import data or create new tables 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 After successful deployment, services will be available at:
2. View all services in one dashboard
3. Monitor service status
4. Quick access to all applications
## 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 ### Environment Variables
Key settings in `.env` file: Key settings in `.env` file:
```env ```env
# Service Ports # Domain Configuration
DOMAIN=yourdomain.com
BASE_DOMAIN=https://yourdomain.com
# Service Ports (automatically assigned to avoid conflicts)
HOMEPAGE_PORT=3010 HOMEPAGE_PORT=3010
CODE_SERVER_PORT=8888 CODE_SERVER_PORT=8888
LISTMONK_PORT=9000
MKDOCS_PORT=4000 MKDOCS_PORT=4000
MKDOCS_SITE_SERVER_PORT=4001 MKDOCS_SITE_SERVER_PORT=4001
LISTMONK_PORT=9000
N8N_PORT=5678 N8N_PORT=5678
NOCODB_PORT=8090 NOCODB_PORT=8090
GITEA_WEB_PORT=3030
GITEA_SSH_PORT=2222
MAP_PORT=3000
MINI_QR_PORT=8089
# Database # Cloudflare (for production)
POSTGRES_USER=listmonk CF_API_TOKEN=your_token
POSTGRES_PASSWORD=your_secure_password CF_ZONE_ID=your_zone_id
POSTGRES_DB=listmonk CF_ACCOUNT_ID=your_account_id
# User/Group IDs (match your system)
USER_ID=1000
GROUP_ID=1000
``` ```
### Volume Mounts ### Reconfigure Services
Important directories: To update configuration:
- `./mkdocs/`: Documentation source files ```bash
- `./configs/`: Service configurations # Re-run configuration wizard
- `./assets/`: Shared assets and uploads ./config.sh
- Docker volumes for persistent data
# Restart services
docker compose down && docker compose up -d
```
## Common Tasks ## Common Tasks
### Writing Documentation ### Service Management
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
```bash ```bash
# View logs # View all services
docker compose logs [service-name] docker compose ps
# Restart service # View logs for specific service
docker compose logs -f [service-name]
# Restart a service
docker compose restart [service-name] docker compose restart [service-name]
# Stop all services # Stop all services
docker compose down docker compose down
# Update services # Stop and remove all data (CAUTION!)
docker compose pull && docker compose up -d docker compose down -v
``` ```
### Backup Important Data ### Backup Data
- Export n8n workflows ```bash
- Backup PostgreSQL database # Backup all volumes
- Version control your documentation files docker run --rm -v changemaker_listmonk-data:/data -v $(pwd):/backup alpine tar czf /backup/listmonk-backup.tar.gz -C /data .
- Save service configurations
# 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 ## Troubleshooting
### Port Conflicts ### Port Conflicts
If ports are already in use, edit `.env` file: If services fail to start due to port conflicts:
```env 1. Check which ports are in use:
CODE_SERVER_PORT=8889 # Change from 8888 ```bash
MKDOCS_PORT=4002 # Change from 4000 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 ### Permission Issues
Ensure correct user/group IDs in `.env`: Fix permission problems:
```bash ```bash
# Get your user ID # Get your user and group IDs
id -u id -u # User ID
id -g # Group ID
# Get your group ID # Update .env file with correct IDs
id -g 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 ### Service Won't Start
Check logs for specific errors: Debug service issues:
```bash ```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: ### Cloudflare Tunnel Issues
- Port conflicts
- Permission problems ```bash
- Missing environment variables # Check tunnel service status
- Network connectivity sudo systemctl status cloudflared-changemaker
# View tunnel logs
sudo journalctl -u cloudflared-changemaker -f
# Restart tunnel
sudo systemctl restart cloudflared-changemaker
```
## Next Steps ## Next Steps
- Explore the [Services](services/index.md) documentation Now that your Changemaker Lite instance is running:
- Set up your first [n8n workflow](services/n8n.md)
- Configure [Listmonk](services/listmonk.md) for email campaigns 1. **Set up Listmonk** - Configure SMTP and create your first campaign
- Customize your [MkDocs](services/mkdocs.md) theme and content 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 ## Getting Help
- Check service-specific documentation - Check the [Services](services/index.md) documentation for detailed guides
- Review Docker container logs - Review container logs for specific error messages
- Verify environment configuration - Ensure all prerequisites are properly installed
- Test network connectivity between services - Verify your domain DNS settings for production deployment

74
mkdocs/docs/index.md
View File

@ -1,6 +1,6 @@
# Welcome to Changemaker Lite # 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 ## Quick Start
@ -16,45 +16,87 @@ cd changemaker.lite
# Start all services # Start all services
docker compose up -d docker compose up -d
# For production deployment with Cloudflare tunnels
./start-production.sh
``` ```
## Services ## Services
Changemaker Lite includes these essential 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 - **[Code Server](services/code-server.md)** (Port 8888) - VS Code in your browser
- **[MkDocs](services/mkdocs.md)** (Port 4000) - Documentation with live preview - **[MkDocs](services/mkdocs.md)** (Port 4000) - Documentation with live preview
- **[Static Server](services/static-server.md)** (Port 4001) - Built site hosting - **[Static Server](services/static-server.md)** (Port 4001) - Production documentation site
- **[Waypoint Editor](services/waypoint-editor.md)** (Port 3020) - Visual page editor
- **[Listmonk](services/listmonk.md)** (Port 9000) - Newsletter management ### Communication & Automation
- **[PostgreSQL](services/postgresql.md)** (Port 5432) - Database backend - **[Listmonk](services/listmonk.md)** (Port 9000) - Newsletter and email campaign management
- **[n8n](services/n8n.md)** (Port 5678) - Workflow automation - **[n8n](services/n8n.md)** (Port 5678) - Workflow automation platform
### Data & Development
- **[NocoDB](services/nocodb.md)** (Port 8090) - No-code database platform - **[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 ## Getting Started
1. **Documentation**: Start writing in [Code Server](http://localhost:8888) 1. **Setup**: Run `./config.sh` to configure your environment
2. **Preview**: See live changes at [MkDocs](http://localhost:4000) 2. **Launch**: Start services with `docker compose up -d`
3. **Production**: View built site at [Static Server](http://localhost:4001) 3. **Dashboard**: Access the Homepage at [http://localhost:3010](http://localhost:3010)
4. **Email**: Set up campaigns with [Listmonk](http://localhost:9000) 4. **Production**: Deploy with Cloudflare tunnels using `./start-production.sh`
5. **Automation**: Create workflows in [n8n](http://localhost:5678)
## Project Structure ## Project Structure
``` ```
changemaker.lite/ changemaker.lite/
├── docker-compose.yml # Service definitions ├── docker-compose.yml # Service definitions
├── config.sh # Setup script ├── config.sh # Configuration wizard
├── start-production.sh # Production deployment script
├── mkdocs/ # Documentation source ├── mkdocs/ # Documentation source
│ ├── docs/ # Markdown files │ ├── docs/ # Markdown files
│ └── mkdocs.yml # Configuration │ └── mkdocs.yml # MkDocs configuration
├── configs/ # Service configurations ├── 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 └── 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 ## 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 - [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