85a4115a71
✨ Features: • HTTP/1.1, HTTP/2, and HTTP/3 support with proper architecture • Reverse proxy with advanced load balancing (round-robin, least-conn, etc.) • Static file serving with content-type detection and security • Revolutionary file sync system with WebSocket real-time updates • Enterprise-grade health monitoring (active/passive checks) • TLS/HTTPS with ACME/Let's Encrypt integration • Dead simple JSON configuration + full Caddy v2 compatibility • Comprehensive test suite (72 tests passing) 🏗️ Architecture: • Rust-powered async performance with zero-cost abstractions • HTTP/3 as first-class citizen with shared routing core • Memory-safe design with input validation throughout • Modular structure for easy extension and maintenance 📊 Status: 95% production-ready 🧪 Test Coverage: 72/72 tests passing (100% success rate) 🔒 Security: Memory safety + input validation + secure defaults Built with ❤️ in Rust - Start simple, scale to enterprise!
154 lines
3.4 KiB
Markdown
154 lines
3.4 KiB
Markdown
# 🚀 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. |