Quantum/QUICKSTART.md

🚀 Quantum Quick Start Guide

Get running in 60 seconds or less.

This guide covers the most common Quantum use cases with step-by-step instructions.

🏁 Prerequisites

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Clone and build Quantum
git clone <repository-url>
cd quantum
cargo build --release

📋 Scenario 1: Proxy Your Development Server

Use case: You have a React/Node.js/Python app running on localhost:3000 and want to access it via port 8080.

Step 1: Create config file

echo '{"proxy": {"localhost:3000": ":8080"}}' > proxy.json

Step 2: Start Quantum

cargo run --bin quantum -- --config proxy.json

Step 3: Test it

curl http://localhost:8080
# Your app's response should appear here

✅ Done! Your app is now accessible on port 8080.

---

📁 Scenario 2: Serve Static Files

Use case: You have a built website in ./dist folder and want to serve it.

Step 1: Create config file

echo '{"static_files": {"./dist": ":8080"}}' > static.json

Step 2: Start Quantum

cargo run --bin quantum -- --config static.json

Step 3: Test it

curl http://localhost:8080
# Or open http://localhost:8080 in your browser

✅ Done! Your static site is live on port 8080.

---

☁️ Scenario 3: File Upload/Download Server

Use case: You need a simple file server with upload capabilities.

Step 1: Create upload directory

mkdir uploads
echo "Hello from Quantum!" > uploads/test.txt

Step 2: Create config file

echo '{"file_sync": {"./uploads": ":8080"}}' > upload.json

Step 3: Start Quantum

cargo run --bin quantum -- --config upload.json

Step 4: Test download

curl http://localhost:8080/api/files/test.txt
# Should return: Hello from Quantum!

Step 5: Test upload

echo "Uploaded file!" | curl -X POST \
  -H "Content-Type: text/plain" \
  --data-binary @- \
  http://localhost:8080/api/files/upload/new-file.txt

✅ Done! You have a file server with upload/download API.

---

🌐 Scenario 4: Full-Stack Development Setup

Use case: You have a frontend (React) on port 3000, backend API on port 4000, and want to serve both with file uploads.

Step 1: Create config file

{
  "proxy": {
    "localhost:4000": ":80"
  },
  "static_files": {
    "./frontend/build": ":8080"
  },
  "file_sync": {
    "./uploads": ":9000"
  }
}

Save as fullstack.json

Step 2: Start Quantum

cargo run --bin quantum -- --config fullstack.json

Step 3: Access your services

• API: http://localhost:80 → your backend on localhost:4000
• Frontend: http://localhost:8080 → your built React app
• File uploads: http://localhost:9000/api/files/ → upload/download files

✅ Done! Complete development environment running.

---

🔒 Scenario 5: Production with HTTPS

Use case: Deploy to production with automatic HTTPS certificates.

Step 1: Create production config

{
  "proxy": {
    "localhost:3000": ":443"
  },
  "tls": "auto"
}

Save as production.json

Step 2: Start Quantum (requires domain and port 443)

sudo cargo run --bin quantum -- --config production.json

✅ Done! Your app runs with automatic HTTPS certificates via Let's Encrypt.

---

🔧 Scenario 6: Multiple Services (Microservices)

Use case: You have multiple microservices and want to route them by port.

Step 1: Create microservices config

{
  "proxy": {
    "localhost:3001": ":8001",
    "localhost:3002": ":8002", 
    "localhost:3003": ":8003"
  },
  "static_files": {
    "./admin-ui": ":8080"
  }
}

Save as microservices.json

Step 2: Start Quantum

cargo run --bin quantum -- --config microservices.json

Step 3: Access services

• User Service: http://localhost:8001 → localhost:3001
• Order Service: http://localhost:8002 → localhost:3002
• Payment Service: http://localhost:8003 → localhost:3003
• Admin UI: http://localhost:8080 → ./admin-ui files

✅ Done! All microservices accessible via different ports.

---

🚨 Troubleshooting

❌ "Address already in use"

Solution: Another service is using that port. Either stop it or use a different port:

# Check what's using port 8080
lsof -i :8080

# Use different port
echo '{"proxy": {"localhost:3000": ":8081"}}' > config.json

❌ "Proxy upstream must include port"

Solution: Always specify the port for proxy targets:

# ❌ Wrong
{"proxy": {"localhost": ":8080"}}

# ✅ Correct  
{"proxy": {"localhost:3000": ":8080"}}

❌ "Permission denied" on port 80/443

Solution: Ports below 1024 require root privileges:

# Use sudo for privileged ports
sudo cargo run --bin quantum -- --config config.json

# Or use non-privileged ports
{"proxy": {"localhost:3000": ":8080"}}  # Instead of ":80"

❌ "No such file or directory" for static files

Solution: Check the directory path exists:

# Check directory exists
ls -la ./public

# Use absolute path if needed
{"static_files": {"/full/path/to/public": ":8080"}}

---

📊 Validation Messages

Quantum helps you fix configuration issues:

# ✅ Good config
✅ Detected simple configuration format
HTTP server listening on 0.0.0.0:8080

# ❌ Bad config with helpful message
❌ Proxy upstream 'localhost' must include port (e.g., 'localhost:3000')
⚠️  Port 80 for proxy upstream 'localhost:3000' requires root privileges

---

🎯 Common Config Patterns

Development

{
  "proxy": {"localhost:3000": ":8080"},
  "admin_port": ":2019"
}

Staging

{
  "proxy": {"localhost:3000": ":8080"},
  "static_files": {"./public": ":8081"},
  "file_sync": {"./uploads": ":9000"}
}

Production

{
  "proxy": {"localhost:3000": ":443"},
  "tls": "auto"
}

Content Server

{
  "static_files": {"./public": ":80"},
  "file_sync": {"./uploads": ":8080"}
}

---

🚀 Next Steps

Once you're comfortable with simple configs:

1. Add monitoring: Enable admin API with "admin_port": ":2019"
2. Scale up: Add more proxy targets for load balancing
3. Advanced features: Check docs/api.md for full configuration format
4. File sync clients: Use included sync clients for real-time file synchronization

---

💡 Pro Tips

Quick Commands

# Start with default config (serves current directory on :8080)
cargo run --bin quantum

# Quick proxy setup
echo '{"proxy": {"localhost:3000": ":8080"}}' > config.json && cargo run --bin quantum -- -c config.json

# Quick static server
echo '{"static_files": {"./": ":8080"}}' > config.json && cargo run --bin quantum -- -c config.json

Configuration Testing

# Test config without starting server (coming soon)
cargo run --bin quantum -- --config config.json --check

# Verbose logging for debugging
RUST_LOG=debug cargo run --bin quantum -- --config config.json

File Sync Web UI

When using file_sync, visit http://localhost:PORT in your browser for a modern file management interface with drag & drop uploads.

---

That's it! You now know how to use Quantum for the most common web server scenarios.

For advanced configuration options, see:

• SIMPLE-CONFIG.md - Complete simple configuration guide
• docs/api.md - Full API reference
• docs/development.md - Development and contribution guide