commit
This commit is contained in:
parent
c658f4bd00
commit
7a279ee66d
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user