Architecture Overview
Understanding how Maidan Cloud components work together for secure, scalable community infrastructure.
🏗️ System Architecture
Maidan Cloud uses a modern three-layer architecture designed for reliability, security, and ease of management.
Infrastructure Layer (OpenTofu)
Responsibilities:
- VPS provisioning and configuration
- DNS record management
- Network tunnel setup (Cloudflare)
- Basic security hardening
- SSH key deployment
Matrix Configuration Components:
┌─────────────────────────────────────────────────────────┐
│ INFRASTRUCTURE LAYER │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ VPS │ │ DNS │ │ Networking │ │
│ │ Cherry │◄──►│ Cloudflare │◄──►│ Tunnels │ │
│ │DigitalOcean │ │1984.hosting │ │ Direct IP │ │
│ │1984.hosting │ │ │ │ │ │
│ │Existing VPS │ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────┘
VPS Provider Options:
- Cherry Servers: European hosting, automated provisioning
- DigitalOcean: Global provider, developer-friendly
- 1984.hosting: Iceland-based, sovereignty-focused
- Existing VPS: Bring your own server
Configuration Layer (Ansible)
Responsibilities:
- Operating system security hardening
- Docker and container runtime setup
- Service configuration and secrets management
- SSL certificate automation
- Backup and monitoring setup
Key Components:
┌─────────────────────────────────────────────────────────┐
│ CONFIGURATION LAYER │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Security │ │ Container │ │ Service │ │
│ │ Hardening │◄──►│ Runtime │◄──►│ Config │ │
│ │ UFW+Fail2ban│ │ Docker │ │ Templates │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────┘
Application Layer (Docker Compose)
Responsibilities:
- Service orchestration and dependencies
- Inter-service networking and communication
- Data persistence and volume management
- Health monitoring and auto-recovery
Key Components:
┌─────────────────────────────────────────────────────────┐
│ APPLICATION LAYER │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Core │ │Communication│ │Collaboration│ │
│ │ Traefik │◄──►│ Matrix │◄──►│ CryptPad │ │
│ │ Authentik │ │ Jitsi │ │ LibreChat │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────┘
🔄 Data Flow Architecture
Request Routing (Matrix Configurations)
With Cloudflare Tunnels:
Internet Request → Cloudflare DNS → Cloudflare Tunnel → Traefik → Service
↑ ↑ ↑ ↑
DNS Resolution DDoS Protection SSL Term. Service
Load Balancing Edge Caching Auth. Logic
Direct IP (No Tunnels):
Internet Request → DNS Provider → Direct VPS IP → Traefik → Service
↑ ↑ ↑ ↑
DNS Resolution Server Firewall SSL Term. Service
(CF or 1984) UFW + Fail2ban Auth. Logic
Service Communication
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Frontend │ │ Gateway │ │ Backend │
│ (Browser) │◄──►│ (Traefik) │◄──►│ (Services) │
└─────────────┘ └─────────────┘ └─────────────┘
▲ ▲ ▲
User Requests Route/Authenticate Process/Store
HTTPS Only Rate Limiting Container Network
Authentication Flow
User Login → Authentik SSO → Service Access Token → Service Login
▲ ▲ ▲ ▲
Browser Identity OIDC Token Service
Session Provider Validation Authorization
🌐 Network Architecture
Container Networking
Internal Network (mc_internal):
- All services communicate via internal Docker network
- No external access to internal services
- Secure inter-service communication
External Access (via Traefik):
- Single point of entry for all web traffic
- Automatic HTTPS with Let's Encrypt
- Rate limiting and security headers
Multi-Instance Isolation
┌─────────────────────────────────────────────────────────┐
│ SERVER HARDWARE │
│ │
│ ┌─────────────────┐ ┌─────────────────────────┐ │
│ │ Root Instance │ │ Named Instances │ │
│ │ (mc- prefix) │ │ (mo-, x-, etc.) │ │
│ │ │ │ │ │
│ │ mc-traefik │ │ mo-traefik │ │
│ │ mc-authentik │ │ mo-authentik │ │
│ │ mc-matrix │ │ mo-matrix, x-matrix │ │
│ │ mc_internal │ │ mo_internal, x_internal │ │
│ └─────────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
🔒 Security Architecture
Defense in Depth
Layer 1: Network Security
- Cloudflare DDoS protection (tunnel modes)
- UFW firewall on server
- Non-standard SSH port
- Rate limiting at proxy level
Layer 2: Application Security
- TLS 1.3 encryption for all traffic
- Security headers (XSS, CSP, HSTS)
- Container isolation and non-root users
- Regular security updates
Layer 3: Authentication Security
- Centralized SSO via Authentik
- Strong password policies
- Multi-factor authentication ready
- Session security controls
Layer 4: Data Security
- Encrypted data at rest (where supported)
- Regular automated backups
- Secret management via environment variables
- Audit logging for critical actions
Certificate Management
Let's Encrypt → Traefik → Automatic Renewal → All Services HTTPS
▲ ▲ ▲ ▲
Free SSL Certificate Background Secure
Authority Automation Renewal Connections
📊 Service Dependencies
Deployment Order
Phase 1: Core Infrastructure
Traefik (Gateway) → Authentik (Identity) → Network Foundation
Phase 2: Self-Contained Services
CryptPad, Vaultwarden, mdBook, WordPress, Nextcloud
Phase 3: Dependent Services
Matrix → Element (requires Matrix)
Ollama → LibreChat (requires Ollama)
Phase 4: Resource-Intensive Services
Jitsi, PeerTube, Mattermost (deploy separately for stability)
Service Relationships
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Traefik │◄──►│ Authentik │◄──►│ All │
│ (Gateway) │ │ (SSO) │ │ Services │
└─────────────┘ └─────────────┘ └─────────────┘
▲ ▲ ▲
HTTP Routing Authentication Service
SSL Termination Authorization Logic
Rate Limiting User Management Data Storage
💾 Data Architecture
Persistent Data Volumes
Service Data:
/opt/compose/mdbook/data → Docker Volume → Service Container
▲ ▲
Host Storage Application
Persistent Data Access
Configuration:
Jinja2 Templates → Ansible Processing → Service Config Files
▲ ▲ ▲
Version Control Variable Runtime
Template Files Substitution Configuration
Backups:
Service Data → Backup Script → Cherry Servers Storage → Offsite Backup
▲ ▲ ▲ ▲
Live Data Automated Cloud Storage Geographic
Volumes Schedule 100GB Included Redundancy
🚀 Scaling Architecture
Vertical Scaling (Single Server)
Resource Allocation:
- Memory: Each service configured with appropriate limits
- CPU: Container CPU limits prevent resource starvation
- Storage: Dedicated volumes for each service
- Network: Internal Docker networking for optimal performance
Horizontal Scaling (Multiple Servers)
Multi-Instance Deployment:
# Instance 1: Root domain community
instance_name = "" # Creates mc- containers at domain.com
# Instance 2: Subdomain community
instance_name = "tech" # Creates tech- containers at tech.domain.com
# Instance 3: Another community
instance_name = "arts" # Creates arts- containers at arts.domain.com
Federation Scaling (Network Effect)
Cross-Community Connections:
Community A (Matrix) ←→ Community B (Matrix) ←→ Community C (Matrix)
Community A (Lemmy) ←→ Community B (Lemmy) ←→ Community C (Lemmy)
Community A (Tube) ←→ Community B (Tube) ←→ Community C (Tube)
🔧 Development Architecture
Infrastructure as Code Benefits
Version Control:
- All infrastructure defined in code
- Changes tracked in Git
- Peer review for infrastructure changes
- Rollback capability for failed deployments
Testing Pipeline:
Local Development → Dev Environment → Staging → Production
▲ ▲ ▲ ▲
Docker Compose Test Deployment Integration Live
Local Testing Ansible --check Testing Community
Configuration Management:
group_vars/all.yml → Jinja2 Templates → Service Configs
▲ ▲ ▲
Central Config Dynamic Values Runtime
Variable Storage Template System Application
🎯 Performance Architecture
Caching Strategy
Static Content:
- Traefik serves static files with caching headers
- Cloudflare CDN caches public content (tunnel modes)
- Browser caching for frequently accessed resources
Database Optimization:
- Each service uses appropriate database technology
- Regular database maintenance via Ansible
- Backup scheduling optimized for low-impact times
Resource Monitoring:
Docker Stats → Health Checks → Auto-Restart → Alert Generation
▲ ▲ ▲ ▲
System Resources Service Container Community
CPU/Memory/Disk Health Recovery Notification
Understanding the architecture helps with:
- Troubleshooting: Know where to look when issues arise
- Customization: Modify components that fit your needs
- Scaling: Plan for community growth
- Security: Understand the security model and trust boundaries
Next Steps:
- Deployment Guide - Put this architecture to work
- Security Guide - Deep dive into security features
- Administration Guide - Learn to manage your instance