Prerequisites

Prerequisites

Before installing or using Cloudillo, ensure your system meets the requirements below.

For Self-Hosting (Rust Version)

System Requirements

Minimum:

  • CPU: 1 core (2+ recommended)
  • RAM: 512MB (1GB+ recommended)
  • Disk: 1GB + storage for user data
  • OS: Linux (x86_64 or ARM64), macOS, Windows with WSL2

Recommended for 10+ users:

  • CPU: 2+ cores
  • RAM: 2GB+
  • Disk: 10GB+ SSD
  • OS: Linux (Ubuntu 22.04+ or Debian 12+)

Recommended for 100+ users:

  • CPU: 4+ cores
  • RAM: 8GB+
  • Disk: 50GB+ SSD
  • OS: Linux on dedicated hardware/VPS

Software Requirements

For Docker Installation (recommended):

  • Docker 20.10+
  • Docker Compose 2.0+ (optional but recommended)

For Building from Source:

  • Rust 1.70+ with cargo
  • Git

For Domain-Based Identity:

  • Domain name with DNS control
  • SSL/TLS certificate (Let’s Encrypt supported via ACME)

Network Requirements

Required Ports:

  • 443 (HTTPS) - Required for application access
  • 80 (HTTP) - Required for ACME/Let’s Encrypt certificate validation
  • OR custom ports if using reverse proxy

DNS Records Required:

  • A record: yourdomain.com → server IP address
  • A record: cl-o.yourdomain.com → server IP address

Example:

yourdomain.com          A    203.0.113.42
cl-o.yourdomain.com     A    203.0.113.42

Firewall:

  • Allow inbound TCP on ports 80 and 443
  • Allow outbound HTTPS (443) for federation

Browser Compatibility (for end users)

Supported:

  • Chrome/Edge 90+
  • Firefox 88+
  • Safari 14+

Recommended:

  • Latest stable versions of above browsers
  • JavaScript enabled
  • Cookies enabled

For App Development

Required Software

  • Node.js: 18+ (20+ recommended)
  • pnpm: 8+
  • TypeScript: 5+
  • Git: Latest stable version
  • VS Code with extensions:
    • TypeScript
    • ESLint
    • Prettier
    • React (if building UI apps)
  • Browser DevTools knowledge
  • Postman or similar API testing tool (optional)

Knowledge Prerequisites

  • JavaScript/TypeScript fundamentals
  • Async/await patterns
  • REST API concepts
  • WebSocket basics (for real-time features)
  • React basics (for UI apps using @cloudillo/react)

For Contributing to Cloudillo

Required

  • Rust: 1.70+ with cargo
  • Git: Latest stable version
  • GitHub account
  • SQLite: 3.x (for testing adapters)
  • Docker: For testing deployments
  • Rust experience:
    • Understanding of Tokio/async Rust
    • Familiarity with Axum web framework
    • Knowledge of Rust error handling
  • Testing tools:
    • cargo test
    • cargo clippy
    • cargo fmt

Useful Background

  • Understanding of web server architecture
  • Database experience (SQLite, key-value stores)
  • WebSocket protocols
  • Authentication systems (JWT, OAuth)
  • CRDT concepts (for collaborative editing features)

Deployment Scenarios

Personal/Family Use

Typical setup:

  • 1-20 users
  • Home server or small VPS
  • 1 vCPU, 512MB-1GB RAM, 50GB disk

Recommended:

  • Raspberry Pi 4 (4GB+)
  • Small VPS ($5-10/month)
  • Docker installation

Small Organization (10-50 users)

Typical setup:

  • 10-50 users
  • VPS or cloud instance
  • 2 vCPU, 1-2GB RAM, 500GB disk

Recommended:

  • DigitalOcean Droplet / AWS t3.small
  • Docker with monitoring
  • Regular backups

Community Server (50-500 users)

Typical setup:

  • 50-500 users
  • Dedicated server or powerful VPS
  • 2-4 vCPU, 4-8GB RAM, 1TB+ SSD

Recommended:

  • Dedicated server or large VPS
  • Load balancing (if high traffic)
  • Database optimization
  • CDN for static assets
  • Professional monitoring

Development/Testing

Typical setup:

  • Local development machine
  • 2+ cores, 4GB+ RAM, 20GB disk
  • Docker or build from source

Recommended:

  • Modern laptop/desktop
  • Fast SSD for rebuilds
  • Multiple browser for testing
  • Local domain setup (hosts file)

Quick Checklist

Before proceeding with installation, verify:

Self-Hosting Checklist

  • Server meets minimum requirements (1 core, 512MB RAM, 1GB disk)
  • Docker 20.10+ installed OR Rust 1.70+ installed
  • Domain name registered and DNS configured
  • Ports 80 and 443 accessible (firewall configured)
  • SSH access to server (if remote)
  • Backup plan in place

Development Checklist

  • Node.js 18+ installed
  • pnpm 8+ installed
  • TypeScript 5+ installed
  • Code editor ready (VS Code recommended)
  • Git configured
  • Access to Cloudillo instance (for testing)

Contributing Checklist

  • Rust 1.70+ installed
  • GitHub account created
  • Repository forked/cloned
  • Tests running (cargo test)
  • Code style configured (cargo fmt, cargo clippy)
  • Architecture documentation reviewed

Verification Commands

Check Docker Installation

docker --version
# Should show: Docker version 20.10+ or higher

docker compose version
# Should show: Docker Compose version 2.0+ or higher

Check Rust Installation

rustc --version
# Should show: rustc 1.70.0 or higher

cargo --version
# Should show: cargo 1.70.0 or higher

Check Node.js Installation

node --version
# Should show: v18.0.0 or higher

pnpm --version
# Should show: 8.0.0 or higher

Check DNS Configuration

# Check A records
dig yourdomain.com A
dig cl-o.yourdomain.com A

# Or use nslookup
nslookup yourdomain.com
nslookup cl-o.yourdomain.com

Check Port Accessibility

# Check if ports are open (from another machine)
nc -zv yourserver.com 80
nc -zv yourserver.com 443

# Or use telnet
telnet yourserver.com 80
telnet yourserver.com 443

Common Issues

“Cannot connect to Docker daemon”

Solution: Start Docker service

sudo systemctl start docker
sudo systemctl enable docker

“Port 443 already in use”

Solution:

  • Check what’s using port 443: sudo lsof -i :443
  • Stop conflicting service or use reverse proxy
  • Configure Cloudillo to use alternate port

“DNS records not propagating”

Solution:

  • Wait 24-48 hours for DNS propagation
  • Use TTL of 300 seconds for faster updates
  • Verify with multiple DNS checkers online

“Rust compiler version too old”

Solution: Update Rust

rustup update stable
rustup default stable

Next Steps

Once your system meets the prerequisites:

  1. Self-Hosting: Install Cloudillo →
  2. Development: Getting Started Guide →
  3. Contributing: Architecture Documentation →

Need Help?