Quantum/SIMPLE-CONFIG.md

🚀 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

{
  "proxy": {
    "localhost:3000": ":8080"
  }
}

Result: Proxy all requests from port 8080 to your app running on localhost:3000

Serve Static Files

{
  "static_files": {
    "./public": ":8080",
    "./uploads": ":9000"
  }
}

Result: Serve files from ./public on port 8080 and ./uploads on port 9000

File Sync (Upload/Download)

{
  "file_sync": {
    "./shared": ":8080"
  }
}

Result: Enable file upload/download API on port 8080 for the ./shared directory

Full Stack Setup

{
  "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

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

Production with TLS

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

File Server with Uploads

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

Multi-Service

{
  "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:

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

2. Run Quantum:

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.