# 🚀 Simple Configuration Guide

Quantum supports a dead-simple configuration format for common use cases. No nested objects, no complex matchers - just tell us what you want to serve!

## 📖 Quick Examples

### Proxy to Backend
```json
{
  "proxy": {
    "localhost:3000": ":8080"
  }
}
```
**Result:** Proxy all requests from port 8080 to your app running on localhost:3000

### Serve Static Files
```json
{
  "static_files": {
    "./public": ":8080",
    "./uploads": ":9000"
  }
}
```
**Result:** Serve files from `./public` on port 8080 and `./uploads` on port 9000

### File Sync (Upload/Download)
```json
{
  "file_sync": {
    "./shared": ":8080"
  }
}
```
**Result:** Enable file upload/download API on port 8080 for the `./shared` directory

### Full Stack Setup
```json
{
  "proxy": {
    "localhost:3000": ":80",
    "localhost:4000": ":443"
  },
  "static_files": {
    "./public": ":8080"
  },
  "file_sync": {
    "./uploads": ":9000"
  },
  "tls": "auto",
  "admin_port": ":2019"
}
```

## 🎯 Configuration Options

| Field | Description | Example |
|-------|-------------|---------|
| `proxy` | Backend services to proxy to | `{"localhost:3000": ":80"}` |
| `static_files` | Directories to serve as static files | `{"./public": ":8080"}` |
| `file_sync` | Directories with upload/download API | `{"./uploads": ":9000"}` |
| `tls` | TLS mode: "auto", "off", or cert path | `"auto"` |
| `admin_port` | Admin API port (optional) | `":2019"` |

## ✅ Validation Features

The simple config includes helpful validation:

- **Port validation**: Warns about privileged ports (< 1024)
- **Upstream validation**: Ensures proxy targets include ports
- **Empty checks**: Prevents empty directories or upstreams
- **TLS validation**: Validates TLS settings

## 🔧 Port Formats

All these formats work:
- `":8080"` - Listen on all interfaces, port 8080
- `"8080"` - Same as above (colon added automatically)
- `"127.0.0.1:8080"` - Listen only on localhost
- `"[::1]:8080"` - IPv6 localhost

## 💡 Common Patterns

### Development Setup
```json
{
  "proxy": { "localhost:3000": ":8080" },
  "static_files": { "./public": ":8081" }
}
```

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

### File Server with Uploads
```json
{
  "static_files": { "./public": ":80" },
  "file_sync": { "./uploads": ":8080" }
}
```

### Multi-Service
```json
{
  "proxy": {
    "localhost:3000": ":80",
    "localhost:3001": ":8080", 
    "localhost:3002": ":9000"
  }
}
```

## 🚫 Error Messages

If something's wrong, you'll get helpful messages:

```
❌ Proxy upstream 'localhost' must include port (e.g., 'localhost:3000')
⚠️  Port 80 for proxy upstream 'localhost:3000' requires root privileges
❌ Invalid port 'abc' for static files './public'
```

## 🔄 Migration from Full Config

The simple format automatically converts to the full Caddy format internally. If you need advanced features like:
- Custom matchers (host, path, method)
- Advanced load balancing
- Health checks
- Custom middleware

Use the full configuration format instead.

## 🎉 Getting Started

1. Create a simple config file:
```bash
echo '{"proxy": {"localhost:3000": ":8080"}}' > config.json
```

2. Run Quantum:
```bash
quantum --config config.json
```

3. That's it! Your server is running.

The simple format handles 90% of common use cases with minimal configuration. Start simple, then migrate to the full format when you need advanced features.