Deployment Guide

Get your own Maidan Cloud instance running in under an hour with Infrastructure as Code.

Maidan Cloud uses modern Infrastructure as Code (IaC) tools to make deployment simple, reliable, and reproducible. Whether you're setting up for a small community or a large organization, the process is the same.

🚀 Why Infrastructure as Code?

Reproducible Deployments

  • Every deployment is identical and predictable
  • No manual configuration steps that can be forgotten
  • Easy to replicate across development, staging, and production

Security by Default

  • Enterprise-grade security configurations applied automatically
  • Regular security updates without manual intervention
  • Secrets management and credential rotation built-in

Community Maintained

  • Configuration improvements benefit all users
  • Well-tested deployment patterns
  • Community-driven fixes and features

📋 Prerequisites

Required Accounts & Tools

Development Machine:

  • OpenTofu/Terraform v1.x+ (Infrastructure provisioning)
  • Ansible 2.10+ (Service configuration)
  • SSH keypair for secure server access
  • Git for cloning the repository

Service Provider Accounts (choose your configuration):

Maidan Cloud supports a flexible matrix configuration with multiple provider combinations:

VPS Providers (choose one):

  • Cherry Servers - European hosting with automated provisioning
  • DigitalOcean - Global provider with familiar developer experience
  • 1984.hosting - Iceland-based sovereignty-focused hosting
  • Existing VPS - Bring your own server (manual setup)

DNS Providers (choose one):

  • Cloudflare - Global DNS with free tier and performance optimization
  • 1984.hosting - Privacy-focused DNS management

Networking (choose one):

  • Cloudflare Tunnels - Traffic routed through CF edge (enhanced security)
  • Direct IP - Traffic directly to your VPS (simpler setup)

Popular Combinations:

  • Cherry + Cloudflare + Tunnels (Default - ease + performance)
  • DigitalOcean + Cloudflare + Tunnels (Familiar + performance)
  • 1984.hosting + 1984.hosting + Direct (Maximum sovereignty)

Technical Requirements

VPS Specifications:

  • Minimum: 2 CPU cores, 4GB RAM, 50GB SSD
  • Recommended: 4 CPU cores, 8GB RAM, 100GB SSD
  • Operating System: Ubuntu 22.04 LTS (auto-configured)
  • Network: Public IPv4 address

🏗️ Architecture Overview

Three-Layer Stack

┌─────────────────────────────────────────────────────────┐
│                    APPLICATION LAYER                     │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│  │   Matrix    │ │ LibreChat   │ │    14 Services      │ │
│  │    Chat     │ │     AI      │ │      Total          │ │
│  └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│                 CONFIGURATION LAYER                     │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│  │   Ansible   │ │  Security   │ │     Service         │ │
│  │ Automation  │ │  Hardening  │ │   Configuration     │ │
│  └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────┐
│                 INFRASTRUCTURE LAYER                    │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│  │  OpenTofu   │ │ DNS Setup   │ │      VPS            │ │
│  │ Provisioning│ │& Tunnels    │ │   Provisioning      │ │
│  └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Multi-Instance Support

Deploy multiple independent communities under one domain:

  • Root Domain: maidan.cloud (main community)
  • Instance Domains: mo.maidan.cloud, x.maidan.cloud (sub-communities)
  • Container Isolation: Each instance uses separate containers (mc-, mo-, x-)

🛠️ Deployment Process

Step 1: Get the Code

# Clone the repository
git clone [GITHUB_LINK_COMING_SOON] maidan-cloud
cd maidan-cloud

# Verify security scanning tools
./scripts/check-secrets.sh

Step 2: Choose Your Configuration

Matrix Configuration (Recommended):

# DigitalOcean + Cloudflare + Tunnels (familiar + performance)
cp examples/digitalocean-cloudflare-tunnels.tfvars opentofu/main/secret.auto.tfvars

# Full 1984.hosting stack (maximum sovereignty)
cp examples/1984hosting-full-stack.tfvars opentofu/main/secret.auto.tfvars

# Existing VPS + Cloudflare (bring your own server)
cp examples/existing-vps-cloudflare.tfvars opentofu/main/secret.auto.tfvars

Legacy Mode Selection (Still Supported):

# Cloudflare Mode (easiest, best performance)
cp examples/cloudflare-deployment.tfvars opentofu/main/secret.auto.tfvars

# 1984.hosting Mode (maximum digital sovereignty)  
cp examples/1984hosting-deployment.tfvars opentofu/main/secret.auto.tfvars

Step 3: Configure Your Instance

Edit opentofu/main/secret.auto.tfvars:

Matrix Configuration Example:

# Your domain
base_domain = "yourcommunity.org"
instance_name = ""  # Empty for root domain

# Matrix Configuration: DigitalOcean + Cloudflare + Tunnels
vps_provider = "digitalocean"
dns_provider_matrix = "cloudflare"
tunnel_mode = "enabled"

# Provider credentials
do_api_token = "your_digitalocean_token_here"
cf_api_token = "your_cloudflare_token_here"

# SSH key for server access
ssh_public_key_path = "~/.ssh/id_rsa.pub"

Legacy Configuration Example:

# Your domain
base_domain = "yourcommunity.org"
instance_name = ""  # Empty for root domain

# Legacy mode
deployment_mode = "cloudflare"

# Provider credentials
cloudflare_api_token = "your_cloudflare_token_here"
cherry_auth_token = "your_cherry_servers_token_here"

# SSH key for server access
ssh_public_key_path = "~/.ssh/id_rsa.pub"

Step 4: Deploy Infrastructure

# Initialize and deploy with OpenTofu
cd opentofu/main
tofu init
tofu plan    # Review what will be created
tofu apply   # Deploy infrastructure

# Capture tunnel tokens for service deployment
export TUNNEL_TOKENS=$(tofu output -json tunnel_tokens)

What This Creates:

  • VPS server with Ubuntu 22.04
  • DNS records for all services
  • Cloudflare tunnels (if using tunnel mode)
  • SSH access configuration
  • Basic firewall setup

Step 5: Deploy Services

# Move to Ansible directory
cd ../../ansible

# Install required Ansible collections
ansible-galaxy install -r requirements.yml

# Deploy all services (recommended for production)
ansible-playbook -i inventory/main.ini deploy-all-batched.yml \
  -e "tunnel_tokens=$TUNNEL_TOKENS"

Alternative Deployment Options:

# Deploy specific services only
ansible-playbook -i inventory/main.ini site.yml \
  -e "services=['traefik','authentik','matrix','librechat']" \
  -e "tunnel_tokens=$TUNNEL_TOKENS"

# Deploy using service sets
ansible-playbook -i inventory/main.ini site.yml \
  -e "service_set=communication" \
  -e "tunnel_tokens=$TUNNEL_TOKENS"

# Available service sets:
# - minimal: traefik, authentik, wordpress
# - core: traefik, authentik  
# - communication: matrix, element, jitsi, mattermost
# - collaboration: pad, vaultwarden, nextcloud
# - knowledge: librechat, ollama, mdbook
# - full: all 16 services

Step 6: Get Admin Access

# Generate admin credentials for all services
./scripts/generate-admin-credentials.sh

# This creates admin-credentials.secret with:
# - All service URLs
# - Admin usernames and passwords  
# - Setup instructions for each service

🎯 Service Access

After deployment, your services will be available at:

Core Services:

  • Community Hub: https://maidan.cloud/
  • Identity Management: https://id.maidan.cloud/
  • Documentation: https://docs.maidan.cloud/

Communication:

  • Matrix Chat: https://matrix.maidan.cloud/
  • Video Calls: https://jitsi.maidan.cloud/

Collaboration:

  • AI Assistant: https://ai.maidan.cloud/
  • Documents: https://pad.maidan.cloud/
  • Videos: https://tube.maidan.cloud/

🔒 Security Features

Automatically Configured:

  • TLS Encryption: All services use HTTPS with automatic certificate management
  • Firewall Protection: UFW firewall blocks unauthorized access
  • Intrusion Detection: Fail2ban protects against brute force attacks
  • System Auditing: Auditd monitors critical system changes
  • Container Security: All services run as non-root users
  • Backup Integration: Automatic backup to Cherry Servers storage

Security Scanning:

# Always run before commits to prevent credential leaks
./scripts/check-secrets.sh

🔧 Customization Options

Service Selection

Deploy only what your community needs:

# Minimal community platform
ansible-playbook -i inventory/main.ini site.yml -e "service_set=minimal"

# Communication-focused deployment  
ansible-playbook -i inventory/main.ini site.yml -e "service_set=communication"

# Full-featured community platform
ansible-playbook -i inventory/main.ini site.yml -e "service_set=full"

Multi-Community Hosting

Host multiple communities on one server:

# Deploy root community
tofu apply -var="instance_name="  # Creates mc- containers

# Deploy additional communities
tofu apply -var="instance_name=community1"  # Creates community1- containers
tofu apply -var="instance_name=community2"  # Creates community2- containers

Development vs Production

# Development deployment with debug features
ansible-playbook -i inventory/dev.ini site.yml -e "environment=dev"

# Production deployment with full security
ansible-playbook -i inventory/main.ini site.yml -e "environment=prod"

🚨 Troubleshooting

Common Issues

Deployment Fails:

# Check OpenTofu state
cd opentofu/main && tofu show

# Verify Ansible connectivity
cd ../../ansible && ansible-playbook -i inventory/main.ini site.yml --check

# Review service logs
docker logs <container-name>

Services Not Accessible:

# Check Traefik routing
curl -s http://localhost:8080/api/http/routers | jq

# Verify DNS propagation
nslookup id.maidan.cloud

# Test internal connectivity
docker exec <container> curl -f http://internal-service:port

SSL Certificate Issues:

# Check Traefik certificates
docker logs mc-traefik | grep -i cert

# Verify domain ownership
curl -I https://maidan.cloud

Getting Help

  • Community Support: Join our Matrix network for help
  • Documentation: Check service-specific guides in this documentation
  • Issues: Report bugs on GitHub (link coming soon)
  • Security: Follow responsible disclosure process

🔄 Updates & Maintenance

Regular Updates

# Update service configurations
cd ansible && git pull
ansible-playbook -i inventory/main.ini site.yml

# Update infrastructure
cd opentofu/main && git pull  
tofu plan && tofu apply

Backup & Recovery

# Manual backup
./scripts/cherry-server-backup.sh

# Restore from backup
./scripts/restore-from-backup.sh [backup-date]

Ready to deploy? Start with Step 1 above, or explore our Architecture Guide to understand how everything fits together.

Questions about deployment modes? See our Deployment Mode Comparison to choose the best option for your community.