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

```bash
# 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
```bash
echo '{"proxy": {"localhost:3000": ":8080"}}' > proxy.json
```

### Step 2: Start Quantum
```bash
cargo run --bin quantum -- --config proxy.json
```

### Step 3: Test it
```bash
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
```bash
echo '{"static_files": {"./dist": ":8080"}}' > static.json
```

### Step 2: Start Quantum
```bash
cargo run --bin quantum -- --config static.json
```

### Step 3: Test it
```bash
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
```bash
mkdir uploads
echo "Hello from Quantum!" > uploads/test.txt
```

### Step 2: Create config file
```bash
echo '{"file_sync": {"./uploads": ":8080"}}' > upload.json
```

### Step 3: Start Quantum
```bash
cargo run --bin quantum -- --config upload.json
```

### Step 4: Test download
```bash
curl http://localhost:8080/api/files/test.txt
# Should return: Hello from Quantum!
```

### Step 5: Test upload
```bash
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
```json
{
  "proxy": {
    "localhost:4000": ":80"
  },
  "static_files": {
    "./frontend/build": ":8080"
  },
  "file_sync": {
    "./uploads": ":9000"
  }
}
```

Save as `fullstack.json`

### Step 2: Start Quantum
```bash
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
```json
{
  "proxy": {
    "localhost:3000": ":443"
  },
  "tls": "auto"
}
```

Save as `production.json`

### Step 2: Start Quantum (requires domain and port 443)
```bash
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
```json
{
  "proxy": {
    "localhost:3001": ":8001",
    "localhost:3002": ":8002", 
    "localhost:3003": ":8003"
  },
  "static_files": {
    "./admin-ui": ":8080"
  }
}
```

Save as `microservices.json`

### Step 2: Start Quantum
```bash
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:
```bash
# 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:
```bash
# ❌ Wrong
{"proxy": {"localhost": ":8080"}}

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

### ❌ "Permission denied" on port 80/443
**Solution:** Ports below 1024 require root privileges:
```bash
# 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:
```bash
# 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:

```bash
# ✅ 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
```json
{
  "proxy": {"localhost:3000": ":8080"},
  "admin_port": ":2019"
}
```

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

### Production
```json
{
  "proxy": {"localhost:3000": ":443"},
  "tls": "auto"
}
```

### Content Server
```json
{
  "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](docs/api.md) for full configuration format
4. **File sync clients:** Use included sync clients for real-time file synchronization

---

## 💡 Pro Tips

### Quick Commands
```bash
# 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
```bash
# 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](SIMPLE-CONFIG.md)** - Complete simple configuration guide
- **[docs/api.md](docs/api.md)** - Full API reference
- **[docs/development.md](docs/development.md)** - Development and contribution guide