Phase 11: Zero-Config Defaults

Goal

Make bext run . a production-grade server with zero configuration — smart defaults for everything, auto-detection of the deployment context, and progressive disclosure of config options. Inspired by Caddy's "2-line Caddyfile" and FrankenPHP's "just works" philosophy.

Current State

• bext run . auto-detects framework, generates config, starts server
• Reasonable defaults for cache, workers, rate limits
• But: no TLS by default, no compression auto-tuning, no security defaults
• Config required for domains, upstreams, WAF rules

Design Philosophy

Progressive disclosure: Works with zero config. First config line unlocks new capabilities. Full config available for power users.

Zero config:      bext run .
                  → auto-detect framework, self-signed TLS on localhost,
                    gzip+br compression, 4 workers, ISR cache, health endpoint

One line config:  domain = "example.com"
                  → auto-HTTPS via Let's Encrypt, H2+H3, Early Hints for
                    detected assets, security headers, OCSP stapling

Full config:      bext.config.toml (all knobs)

Auto-Detection Matrix

Smart Defaults Table

Environment Variable Overrides

Every config option can be overridden via environment variable with BEXT_ prefix:

# Instead of bext.config.toml
BEXT_DOMAIN=example.com
BEXT_LISTEN=0.0.0.0:443
BEXT_WORKERS=8
BEXT_CACHE_TTL=120000
BEXT_REDIS_URL=redis://localhost:6379
BEXT_LOG_FORMAT=json
BEXT_WAF=on

Precedence: CLI flags > env vars > config file > auto-detected defaults.

One-Line Quick Start Modes

# Development (auto-detect everything)
bext run .

# Production with domain (auto-HTTPS, security, compression)
bext run . --domain example.com

# Multi-app platform
bext serve

# Static site
bext static ./public

# Proxy mode (no rendering, just reverse proxy + cache)
bext proxy --upstream http://localhost:3001 --domain example.com

Implementation

Config Resolution Pipeline

fn resolve_config(
    cli_args: &CliArgs,
    env: &Environment,
    config_file: Option<&BextConfig>,
) -> ResolvedConfig {
    // 1. Start with auto-detected defaults
    let mut config = auto_detect_defaults(env);

    // 2. Merge config file (if exists)
    if let Some(file) = config_file {
        config.merge(file);
    }

    // 3. Override with environment variables
    config.apply_env_overrides(env);

    // 4. Override with CLI flags
    config.apply_cli_overrides(cli_args);

    // 5. Apply smart defaults based on resolved state
    config.apply_smart_defaults();

    config
}

fn auto_detect_defaults(env: &Environment) -> ResolvedConfig {
    let cpu_count = num_cpus::get();
    let total_memory = sys_info::mem_info().unwrap().total;
    let has_domain = env.var("DOMAIN").is_some() || env.var("SERVER_NAME").is_some();
    let has_redis = env.var("REDIS_URL").is_some();
    let port_443_available = check_port_available(443);

    ResolvedConfig {
        workers: cpu_count.min(8),
        max_memory_mb: (total_memory / (cpu_count as u64 * 2 * 1024)) as u32,
        tls: if has_domain { TlsMode::Auto } else { TlsMode::SelfSigned },
        h2: true,
        h3: has_domain,  // Only with real domain
        compression: CompressionConfig::default(),
        early_hints: has_domain,  // Auto-discover with domain
        cache: CacheConfig::default(),
        waf: if has_domain { WafMode::Basic } else { WafMode::Off },
        redis: has_redis,
        listen: if port_443_available && has_domain {
            "0.0.0.0:443".into()
        } else {
            "0.0.0.0:3000".into()
        },
        ..Default::default()
    }
}

Startup Banner

Show resolved configuration on startup:

  ╔══════════════════════════════════════════════════════════╗
  ║                    bext v0.3.0                          ║
  ╠══════════════════════════════════════════════════════════╣
  ║  Framework:  Next.js (app dir)                          ║
  ║  Domain:     example.com                                ║
  ║  Listen:     https://0.0.0.0:443 (H2 + H3)             ║
  ║  TLS:        Let's Encrypt (auto)                       ║
  ║  Workers:    4 (max 50K req, 512MB each)                ║
  ║  Cache:      10K entries, 60s TTL, Redis L2             ║
  ║  Compress:   gzip + br + zstd                           ║
  ║  WAF:        basic (sqli, xss, traversal)               ║
  ║  Hub:        SSE + WS at /__bext/events                 ║
  ║  Dashboard:  https://localhost/__bext/dashboard          ║
  ║  Metrics:    https://localhost/metrics                   ║
  ║  Health:     https://localhost/health                    ║
  ╚══════════════════════════════════════════════════════════╝

  Ready in 1.2s

Dockerfile Template

FROM ghcr.io/bext/bext:latest

COPY . /app
WORKDIR /app

# Build (framework auto-detected)
RUN bext build .

# Run (zero config, DOMAIN from env at runtime)
CMD ["bext", "run", "."]
EXPOSE 443 80

Docker Compose Example

services:
  web:
    image: ghcr.io/bext/bext:latest
    environment:
      - DOMAIN=example.com
      - REDIS_URL=redis://redis:6379
    ports:
      - "443:443"
      - "80:80"
    volumes:
      - ./app:/app
      - certs:/data/certs    # Persist ACME certs

  redis:
    image: redis:7-alpine

volumes:
  certs:

Testing Plan

Done Criteria

• bext run . works with zero configuration
• Auto-detection of framework, CPU, memory, domain, Redis
• Smart defaults based on deployment context
• Environment variable overrides with BEXT_ prefix
• Config file merging with correct precedence
• CLI flag overrides
• Startup banner showing resolved configuration
• --domain shortcut for production mode
• bext static, bext proxy quick-start modes
• Dockerfile + Docker Compose examples in docs
• All tests passing