Hostsite - Local Development Proxy Server

A powerful local development proxy server for managing multiple sites with HTTPS/HTTP reverse proxy capabilities. Perfect for local development, testing, and debugging multi-service architectures.

✨ Features

• 🔒 HTTPS/HTTP Reverse Proxy: Support both secure and unsecure protocols
• 🌐 Multi-Site Management: Manage multiple local applications with different domains
• 📍 Path-Level Routing: Route different paths to different services on the same domain
• 🚀 WebSocket Support: Full WebSocket (ws/wss) support for real-time applications
• 🔄 Automatic Protocol Conversion: Automatically upgrade protocols (http → https, ws → wss)
• 🖊️ Hosts File Management: Automatically manage system hosts file entries
• 📝 YAML Configuration: Simple YAML-based configuration
• 🔐 SSL Certificate Management: Automatic certificate loading and self-signed cert generation
• ⚡ Zero-Configuration Defaults: Sensible defaults for quick setup
• 🌍 Multi-Language Support: English and Chinese language support

📦 Installation

npm install -g hostsite

Or use it directly:

npx hostsite --version

🚀 Quick Start

1. Create Configuration File

Create a hostsite.yaml file:

name: my-dev-env

proxies:
  app.local: localhost:3000
  api.app.local: localhost:3001
  ws.app.local: ws://localhost:3002

Port Format: domain[:port][/path]

• Port defaults to 443 if omitted
• Example: staging.local:8443 uses port 8443

2. Add to Hosts File (Automatic)

sudo hostsite start

Note: sudo is required because this command modifies /etc/hosts and listens on port 443 (privileged port).

This will:

1. Add entries to /etc/hosts
2. Start the proxy server
3. Listen on port 443 (HTTPS)

3. Access Your Applications

Open your browser and visit:

• https://app.local → proxies to localhost:3000
• https://api.app.local → proxies to localhost:3001
• wss://ws.app.local → proxies to ws://localhost:3002

📚 Documentation

Core Documentation

• CLI Usage Guide - Complete command-line interface reference
• Configuration File Guide - Detailed configuration options and examples
• Directory Structure - Project architecture and module organization

Key Concepts

Main Commands

# Start proxy and manage hosts (requires sudo)
sudo hostsite start [options]

# Start proxy only (no hosts modification, no sudo needed)
hostsite proxy [options]

# Manage hosts file (requires sudo for apply/restore)
sudo hostsite hosts apply [options]
sudo hostsite hosts restore [options]
hostsite hosts show [options]  # No sudo needed

Path-Level Routing

Route different paths to different services on the same domain:

proxies:
  app.local: localhost:3000 # Root path → Service A
  app.local/api: localhost:3001/api # /api/* → Service B
  app.local/admin: localhost:3002 # /admin/* → Service C

Configuration Example

name: development-env

proxies:
  # Front-end applications (default port 443)
  app.dev: localhost:3000
  www.app.dev: localhost:3000

  # Backend APIs
  api.app.dev: localhost:3001
  secure-api.app.dev: https://localhost:3002

  # Real-time services
  chat.app.dev: ws://localhost:3003
  notifications.app.dev: wss://localhost:3004

  # Path-level routing
  platform.dev/users: localhost:3000/users
  platform.dev/orders: localhost:3001/orders
  platform.dev/analytics: localhost:3002/analytics

  # Custom SSL ports
  staging.dev:8443: localhost:3005
  preview.dev:9443: localhost:3006

  # Wildcard domains
  '*.local': localhost:3000

  # Remote services
  gateway.dev: https://api.example.com:443

🎯 Use Cases

Development Environment Setup

# Terminal 1: Start all your services
npm run dev

# Terminal 2: Start hostsite (requires sudo)
sudo hostsite start --config ./config/dev.yaml

Testing Multi-Service Architecture

hostsite proxy --config ./config/test.yaml

CI/CD Integration

# Apply hosts entries (requires sudo)
sudo hostsite hosts apply --config ./config/ci.yaml

# Start proxy only (no sudo needed)
hostsite proxy --config ./config/ci.yaml &

⚙️ Command Reference

Global Options

--config <path>    Configuration file path (default: ./hostsite.yaml)
--help             Show help message
--version          Show version

Start Command

sudo hostsite start [options]
  --ssl-dir <dir>        SSL certificates directory (default: ./ssl)
  --ssl-key <path>       Custom SSL key path
  --ssl-cert <path>      Custom SSL certificate path
  --ssl-ca <path>        Custom CA file path

⚠️ Requires sudo - This command needs administrator privileges because it:

• Modifies /etc/hosts file
• Listens on port 443 (privileged port < 1024)

Proxy Command

hostsite proxy [options]
  Same options as 'start'

Hosts Commands

hostsite hosts show                         # Display current hosts file (no sudo)
sudo hostsite hosts apply                   # Apply hosts entries from config (requires sudo)
sudo hostsite hosts restore                 # Remove hosts entries (requires sudo)
sudo hostsite hosts restore --config <path> # Remove entries from specific config (requires sudo)

🔐 SSL Certificate Management

Automatic Certificate Discovery

Hostsite searches for SSL certificates in this order:

1. Specific domain directory: ./ssl/example.com/
2. Parent domain directory: ./ssl/example/
3. Self-signed fallback: ./ssl/self-signed/

Certificate Directory Structure

ssl/
├── self-signed/              # Fallback self-signed certs
│   ├── cert.pem
│   └── key.pem
├── example.com/              # Specific domain
│   ├── cert.pem
│   └── key.pem
└── api.example.com/          # Subdomain
    ├── cert.pem
    └── key.pem

Generate Self-Signed Certificates

# Hostsite automatically generates if not found
hostsite start

# The self-signed certificate will be generated in ./ssl/self-signed/

🐛 Troubleshooting

SSL Certificate Warnings

Problem: Browser shows untrusted certificate warning

Solution: Use HTTP instead of HTTPS

hostsite start --protocol http --port 8080

Port Already in Use

Problem: Port 443 is already in use

Solution: Use a different port

hostsite start --port 8443

WebSocket Connection Failed

Problem: WebSocket connections fail

Solutions:

1. Verify target service is running
2. Check firewall settings
3. Ensure proxy configuration is correct

Hosts File Issues

Problem: Changes not taking effect

Solution: Restart the system or flush DNS

# macOS
sudo dscacheutil -flushcache

# Linux
sudo systemctl restart nscd

# Windows (PowerShell as Administrator)
ipconfig /flushdns

🤝 Common Patterns

Development Setup

# config/dev.yaml
name: dev-env

proxies:
  app.local: localhost:3000
  api.local: localhost:3001
  admin.local: localhost:3002

Multiple Environments

# Development
hostsite start --config config/dev.yaml

# Testing
hostsite start --config config/test.yaml

# Staging
hostsite start --config config/staging.yaml

Path-Based Microservices

proxies:
  api.local/users: localhost:3001
  api.local/orders: localhost:3002
  api.local/products: localhost:3003
  api.local: localhost:3000 # Default fallback

Mixed Protocols

proxies:
  app.local: localhost:3000 # HTTP
  secure.local: https://localhost:3001 # HTTPS
  ws.local: ws://localhost:3002 # WebSocket
  wss.local: wss://localhost:3003 # WebSocket Secure

📋 Architecture Overview

┌─────────────────────────────────────────┐
│         Client Applications             │
│   (Browser, API Client, etc.)           │
└────────────────┬────────────────────────┘
                 │
                 ▼
    ┌─────────────────────────┐
    │  Hostsite Proxy Server  │
    │  (HTTPS on port 443)    │
    ├─────────────────────────┤
    │ - Request Routing       │
    │ - SSL/TLS Termination   │
    │ - Protocol Conversion   │
    │ - WebSocket Upgrade     │
    └────────────────┬────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
    ┌────────┐  ┌────────┐  ┌────────┐
    │Service │  │Service │  │Service │
    │  A     │  │  B     │  │  C     │
    │ :3000  │  │ :3001  │  │ :3002  │
    └────────┘  └────────┘  └────────┘

🧪 Testing

Run the test suite:

npm test
npm run test:coverage

💻 Development

Setup

npm install

Build

npm run build

Run Tests

npm run check:fix

Available Scripts

npm run type-check      # TypeScript type checking
npm run lint:fix        # ESLint with auto-fix
npm run format:fix      # Prettier formatting
npm run test:coverage   # Jest with coverage
npm run check:fix       # All checks

📝 License

MIT License - see LICENSE for details