Dev server host binding and SSL certificate trust

[MichaelSchmidle]

Problem

When running light up (development mode), Traefik proxies https://app.lvh.me → http://host.docker.internal:3000, but most dev servers fail with Error 500 due to:

1. Host binding: Vite/Nuxt/Next dev servers bind to localhost by default (not accessible from Docker containers)
2. SSL certificate trust: Dev servers making requests to https://api.lvh.me don't trust mkcert certificates

Current Workaround

Users must manually update their dev script:

{
  "dev": "NODE_EXTRA_CA_CERTS=\"$(mkcert -CAROOT)/rootCA.pem\" nuxt dev --host"
}

This requires users to:

• Know about the --host flag for their framework
• Know about mkcert root CA location
• Manually configure each project

Proposed Solution (Option B + light dev wrapper)

Interactive Setup During light init

Detect dev script and offer to update it:

✓ Lightstack project 'playground' initialized

⚠️  Dev server configuration needed:
  Your "dev" script may not be accessible from Traefik proxy.
  
  Current: "nuxt dev"
  Suggested: "NODE_EXTRA_CA_CERTS=\"$(mkcert -CAROOT)/rootCA.pem\" nuxt dev --host"
  
  Update package.json? [Y/n]

Alternative: light dev Wrapper Command

Provide light dev command that wraps user's dev server with correct configuration:

• Auto-detects framework (Nuxt, Vite, Next, etc.)
• Adds --host flag
• Sets NODE_EXTRA_CA_CERTS to mkcert root CA
• Executes user's dev command with proper env vars

Update "Next steps" output:

Next steps:
  Start your app: light dev
  (Or manually: bun dev --host with mkcert CA trusted)

Hybrid Approach (Recommended)

1. During light init: Offer to update dev script interactively
2. Provide light dev: As fallback for users who decline the update
3. Document in output: Show troubleshooting tips if users use manual bun dev

User Preference

Users prefer Option B (interactive update) because:

• Most devs will instinctively run <package-manager> run dev (muscle memory)
• Remembering to use light dev is extra cognitive load across many projects
• Interactive fix during init is one-time setup, then forgotten

Framework Detection Needed

Need to detect and support:

• Nuxt: nuxt dev --host
• Vite: vite --host
• Next.js: Next binds to 0.0.0.0 by default, but may need SSL trust
• Express/Fastify/etc: Custom server configurations

Success Criteria

• User runs light init → interactive prompt to fix dev script
• User runs bun dev → app accessible via https://app.lvh.me (no Error 500)
• Dev server can make requests to https://api.lvh.me (mkcert CA trusted)
• light dev wrapper command available as alternative
• Clear documentation in troubleshooting guide

Related

• Spec 002 (development mode implementation)
• Issue Create console output formatting system #7 (console output formatting - could improve the interactive prompts)

[MichaelSchmidle]

Additional Finding: Vite allowedHosts Configuration

When running with correct flags (--host + SSL trust), Vite blocks the request:

Blocked request. This host ("app.lvh.me") is not allowed.
To allow this host, add "app.lvh.me" to `server.allowedHosts` in vite.config.js.

Root Cause

Vite's dev server has host validation for security. When accessed via app.lvh.me (proxied through Traefik), Vite sees a different host than localhost and blocks it.

Required Fix

Users need to update their vite.config.ts or nuxt.config.ts:

Vite:

export default defineConfig({
  server: {
    allowedHosts: ['.lvh.me'] // Wildcard for all lvh.me subdomains
  }
})

Nuxt:

export default defineNuxtConfig({
  vite: {
    server: {
      allowedHosts: ['.lvh.me']
    }
  }
})

Impact on Solution

The interactive setup during light init should also:

1. Detect if project uses Vite/Nuxt
2. Check if config file exists
3. Offer to update config with allowedHosts setting
4. Or provide clear instructions if user declines

This makes three configuration points needed:

1. package.json dev script → add --host + SSL trust
2. vite.config.ts / nuxt.config.ts → add allowedHosts
3. Framework-specific considerations (Next.js may differ)

All the more reason for the hybrid approach: interactive setup to fix everything at once, with light dev as fallback.

[MichaelSchmidle]

Updated Analysis & Recommendation

After deeper discussion, here's a refined approach that balances DX with Constitutional principles:

Problem Refined

The current hybrid approach (Option B + light dev wrapper) has a critical flaw:

If users accept the package.json update during light init, they still face issues:

1. Different frameworks need different flags (--host vs --hostname 0.0.0.0 vs env vars)
2. Platform-specific syntax (bash vs PowerShell for NODE_EXTRA_CA_CERTS)
3. Users may forget the manual setup after first run when containers auto-restart

If users decline and rely on light dev, they must remember:

• Use light dev instead of muscle-memory bun dev
• Add framework-specific flags: light dev --host (not zero-config anymore)

Recommended Solution: Zero-Config light dev

Make light dev truly zero-config by auto-detecting framework and applying required flags:

light dev  # Just works - no flags needed
light dev --port 4000  # Custom flags passed through

Implementation:

const frameworks = {
  nuxt: { flags: ['--host'] },
  next: { flags: ['--hostname', '0.0.0.0'] },
  vite: { flags: ['--host'] },
  cra: { env: { HOST: '0.0.0.0' } }
};

// Auto-detect + auto-apply
const detected = detectFramework();
const command = buildCommand(detected, userFlags);
spawn(command, { 
  env: { 
    ...process.env, 
    NODE_EXTRA_CA_CERTS: getMkcertCA() 
  } 
});

Fallback Strategy:

• If framework detection fails → run without extra flags
• If server not accessible → show helpful error with manual command

Why This Approach Wins

1. Respects Constitution: No invasive package.json modifications
2. Zero Cognitive Load: light dev just works, no flags to remember
3. Framework Agnostic: Handles Nuxt, Next, Vite, etc. automatically
4. Opt-In Power: Users who want permanent setup can manually update package.json
5. Discoverable: Show light dev in "Next steps" output

Updated "Next steps" Output

Next steps:
  Start your app: light dev

  For permanent setup, update package.json:
    "dev": "NODE_EXTRA_CA_CERTS=\"$(mkcert -CAROOT)/rootCA.pem\" <cmd> --host"

This way:

• Beginners: light dev just works immediately
• Experienced devs: Get hint to update package.json if they prefer
• Everyone: No invasive modifications, user controls their files

Updated Success Criteria

• light dev auto-detects Nuxt, Next, Vite, CRA
• Auto-applies framework-specific network binding flags
• Sets NODE_EXTRA_CA_CERTS automatically (cross-platform)
• Passes through custom flags: light dev --port 4000
• Graceful fallback with helpful errors if detection fails
• "Next steps" shows both quick (light dev) and permanent (manual) options
• Works on Windows, macOS, Linux

Implementation Notes

Framework Detection Priority:

1. Check package.json dependencies (nuxt, next, vite, etc.)
2. Check for framework config files (nuxt.config.ts, vite.config.js)
3. Fallback to generic dev command without extra flags

Cross-Platform Considerations:

• Windows: Use PowerShell-compatible env var syntax
• Unix: Use standard bash syntax
• Or use Node.js spawn() env option (cleaner, platform-agnostic)

Related:

• Complements Spec 002 (dev/deploy separation)
• Builds on PR fix: UX improvements - console output formatting and .gitignore automation #20 (console output improvements)