freealberta/mkdocs/docs/getting-started.md

Getting Started

Welcome to Changemaker Lite! This guide will help you get up and running quickly.

Prerequisites

Before starting, ensure you have:

• Docker installed
• Docker Compose installed
• Git for cloning the repository
• Basic familiarity with terminal/command line

Installation

1. Clone Repository

git clone https://gitea.bnkops.com/admin/Changemaker.git
cd changemaker.lite

2. Configuration

Run the configuration script to set up environment variables:

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

3. Start Services

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.

4. Verify Installation

Check that services are running:

docker compose ps

All services should show as "Up" status.

First Steps

Access the Dashboard

Start with the Homepage Dashboard: http://localhost:3010

• Central hub for all services
• Live status monitoring
• Quick access to all applications

Access Documentation

1. Development Server: http://localhost:4000

   • Live preview with auto-reload
   • Used while writing documentation

2. Production Server: http://localhost:4001

   • Serves built static site
   • Optimized for performance

Start Coding

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

Set Up Email Campaigns

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

Create Workflows

1. Open n8n: http://localhost:5678
2. Log in with admin credentials
3. Create your first workflow
4. Connect different services together

Manage Data with NocoDB

1. Access NocoDB: http://localhost:8090
2. Complete the initial setup
3. Create your first project
4. Import data or create new tables

Access All Services via Homepage

1. Open Homepage: http://localhost:3010
2. View all services in one dashboard
3. Monitor service status
4. Quick access to all applications

Configuration Details

Environment Variables

Key settings in .env file:

# Service Ports
HOMEPAGE_PORT=3010
CODE_SERVER_PORT=8888
MKDOCS_PORT=4000
MKDOCS_SITE_SERVER_PORT=4001
LISTMONK_PORT=9000
N8N_PORT=5678
NOCODB_PORT=8090

# Database
POSTGRES_USER=listmonk
POSTGRES_PASSWORD=your_secure_password
POSTGRES_DB=listmonk

# User/Group IDs (match your system)
USER_ID=1000
GROUP_ID=1000

Volume Mounts

Important directories:

• ./mkdocs/: Documentation source files
• ./configs/: Service configurations
• ./assets/: Shared assets and uploads
• Docker volumes for persistent data

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

# View logs
docker compose logs [service-name]

# Restart service
docker compose restart [service-name]

# Stop all services
docker compose down

# Update services
docker compose pull && docker compose up -d

Backup Important Data

• Export n8n workflows
• Backup PostgreSQL database
• Version control your documentation files
• Save service configurations

Troubleshooting

Port Conflicts

If ports are already in use, edit .env file:

CODE_SERVER_PORT=8889  # Change from 8888
MKDOCS_PORT=4002       # Change from 4000

Then restart: docker compose down && docker compose up -d

Permission Issues

Ensure correct user/group IDs in .env:

# Get your user ID
id -u

# Get your group ID  
id -g

Update .env with these values and restart services.

Service Won't Start

Check logs for specific errors:

docker compose logs [service-name]

Common issues:

• Port conflicts
• Permission problems
• Missing environment variables
• Network connectivity

Next Steps

• Explore the Services documentation
• Set up your first n8n workflow
• Configure Listmonk for email campaigns
• Customize your MkDocs theme and content

Getting Help

• Check service-specific documentation
• Review Docker container logs
• Verify environment configuration
• Test network connectivity between services