Quantum/MIGRATION.md

🔄 Configuration Migration Guide

From Complex Caddy Config to Simple Quantum Config

This guide helps you migrate from complex Caddy v2 configurations to Quantum's simple format, and when to use each format.

📋 Quick Decision Matrix

Use Case	Simple Config	Full Config
Basic reverse proxy	✅ Perfect	❌ Overkill
Static file serving	✅ Perfect	❌ Overkill
File upload/download	✅ Perfect	❌ Overkill
Multiple services on different ports	✅ Perfect	❌ Overkill
Host-based routing	❌ Use full	✅ Required
Path-based routing	❌ Use full	✅ Required
Advanced load balancing	❌ Use full	✅ Required
Health checks	❌ Use full	✅ Required
Custom middleware	❌ Use full	✅ Required

🚀 Migration Examples

1. Basic Reverse Proxy

Before (Full Config):

{
  "admin": {"listen": ":2019"},
  "apps": {
    "http": {
      "servers": {
        "proxy_server": {
          "listen": [":8080"],
          "routes": [
            {
              "handle": [
                {
                  "handler": "reverse_proxy",
                  "upstreams": [
                    {"dial": "localhost:3000"}
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  }
}

After (Simple Config):

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

Result: 90% less configuration, same functionality.

---

2. Static File Server

Before (Full Config):

{
  "admin": {"listen": ":2019"},
  "apps": {
    "http": {
      "servers": {
        "file_server": {
          "listen": [":8080"],
          "routes": [
            {
              "handle": [
                {
                  "handler": "file_server",
                  "root": "./public",
                  "browse": true
                }
              ]
            }
          ]
        }
      }
    }
  }
}

After (Simple Config):

{
  "static_files": {
    "./public": ":8080"
  }
}

Result: 85% less configuration, automatic browse enabled.

---

3. Multi-Service Setup

Before (Full Config):

{
  "admin": {"listen": ":2019"},
  "apps": {
    "http": {
      "servers": {
        "api_server": {
          "listen": [":8080"],
          "routes": [
            {
              "handle": [
                {
                  "handler": "reverse_proxy",
                  "upstreams": [{"dial": "localhost:3000"}]
                }
              ]
            }
          ]
        },
        "static_server": {
          "listen": [":8081"],
          "routes": [
            {
              "handle": [
                {
                  "handler": "file_server",
                  "root": "./public"
                }
              ]
            }
          ]
        },
        "upload_server": {
          "listen": [":8082"],
          "routes": [
            {
              "handle": [
                {
                  "handler": "file_sync",
                  "root": "./uploads",
                  "enable_upload": true
                }
              ]
            }
          ]
        }
      }
    }
  }
}

After (Simple Config):

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

Result: 95% less configuration, much clearer intent.

---

❌ When Simple Config Can't Help

Host-Based Routing

Full Config Required:

{
  "apps": {
    "http": {
      "servers": {
        "gateway": {
          "listen": [":80"],
          "routes": [
            {
              "match": [
                {"matcher": "host", "hosts": ["api.example.com"]}
              ],
              "handle": [
                {
                  "handler": "reverse_proxy",
                  "upstreams": [{"dial": "api-backend:8080"}]
                }
              ]
            },
            {
              "match": [
                {"matcher": "host", "hosts": ["files.example.com"]}
              ],
              "handle": [
                {
                  "handler": "file_server",
                  "root": "./public"
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Why Simple Config Can't Help:

• Requires host-based routing logic
• Multiple services on same port with different domains
• Complex matching rules

---

Path-Based Routing

Full Config Required:

{
  "routes": [
    {
      "match": [
        {"matcher": "path", "paths": ["/api/*"]}
      ],
      "handle": [
        {
          "handler": "reverse_proxy",
          "upstreams": [{"dial": "api-backend:8080"}]
        }
      ]
    },
    {
      "match": [
        {"matcher": "path", "paths": ["/admin/*"]}
      ],
      "handle": [
        {
          "handler": "reverse_proxy",
          "upstreams": [{"dial": "admin-backend:8080"}]
        }
      ]
    },
    {
      "handle": [
        {
          "handler": "file_server",
          "root": "./public"
        }
      ]
    }
  ]
}

Why Simple Config Can't Help:

• Path-based routing to different backends
• Fallback behavior (serve static files for unmatched paths)
• Order-dependent route processing

---

🔄 Hybrid Approach

You can use both formats in different situations:

Development: Simple Config

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

Staging: Simple Config

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

Production: Full Config (Complex Routing)

{
  "apps": {
    "http": {
      "servers": {
        "production": {
          "listen": [":443"],
          "routes": [
            {
              "match": [
                {"matcher": "host", "hosts": ["api.example.com"]},
                {"matcher": "path", "paths": ["/v1/*"]}
              ],
              "handle": [
                {
                  "handler": "reverse_proxy",
                  "upstreams": [
                    {"dial": "backend1:8080"},
                    {"dial": "backend2:8080"}
                  ],
                  "load_balancing": {
                    "selection_policy": {"policy": "least_conn"}
                  },
                  "health_checks": {
                    "active": {
                      "path": "/health",
                      "interval": "30s"
                    }
                  }
                }
              ]
            }
          ],
          "tls": {
            "automation": {
              "policies": [
                {
                  "subjects": ["api.example.com"],
                  "issuer": {
                    "module": "acme",
                    "email": "admin@example.com",
                    "agreed": true
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
}

---

🛠️ Migration Process

Step 1: Identify Your Use Case

Ask yourself:

• Single service per port? → Use simple config
• Multiple services on same port? → Use full config
• Need custom routing? → Use full config
• Need advanced features? → Use full config

Step 2: Convert Gradually

Start with simple config for basic services:

1. Extract basic proxy mappings
2. Extract static file servers
3. Extract file sync handlers
4. Keep complex routing in full config

Step 3: Test Configuration

# Test simple config
quantum --config simple.json

# Test full config
quantum --config full.json

# Quantum auto-detects the format

Step 4: Validate

Quantum provides helpful validation:

✅ Detected simple configuration format
✅ Detected full Caddy configuration format

❌ Proxy upstream 'localhost' must include port (e.g., 'localhost:3000')

---

📊 Migration Checklist

Before Migration

• Understand current configuration complexity
• Identify which services can use simple config
• Backup current configuration
• Plan migration strategy

During Migration

• Convert simple services first
• Test each service independently
• Validate configuration with Quantum
• Keep complex routing in full format

After Migration

• Verify all services work correctly
• Update documentation
• Train team on new configuration format
• Monitor for any issues

---

🎯 Best Practices

Do's

✅ Start simple - Use simple config for new services ✅ Migrate gradually - Convert one service at a time ✅ Test thoroughly - Validate each migration step ✅ Keep it mixed - Use both formats as needed ✅ Document changes - Update team documentation

Don'ts

❌ Don't migrate everything at once - Too risky ❌ Don't force simple config - Use full config when needed ❌ Don't ignore validation - Pay attention to error messages ❌ Don't skip testing - Always verify functionality ❌ Don't overcomplicate - Simple is often better

---

🔍 Common Migration Patterns

Pattern 1: Development → Production

# Development (simple)
{"proxy": {"localhost:3000": ":8080"}}

# Production (full with health checks)
{"apps": {"http": {"servers": {...complex routing...}}}}

Pattern 2: Microservice Split

# Before (monolith proxy)
{"proxy": {"localhost:3000": ":8080"}}

# After (multiple services)
{
  "proxy": {
    "localhost:3001": ":8080", 
    "localhost:3002": ":8081",
    "localhost:3003": ":8082"
  }
}

Pattern 3: Add Static Assets

# Before (just proxy)
{"proxy": {"localhost:3000": ":8080"}}

# After (proxy + static)
{
  "proxy": {"localhost:3000": ":8080"},
  "static_files": {"./public": ":8081"}
}

---

🚀 Next Steps

After migration:

1. Monitor performance - Ensure no regressions
2. Update automation - CI/CD scripts, deployment tools
3. Train team - Share new configuration approaches
4. Iterate - Continue simplifying where possible
5. Contribute - Share experiences with the community

---

Remember: The goal is simplicity where possible, complexity only when necessary.

For more information:

• SIMPLE-CONFIG.md - Complete simple configuration guide
• QUICKSTART.md - Common usage scenarios
• docs/api.md - Full API reference