LiteGate

# LiteGate [](LICENSE) [](go.mod) [](https://github.com/jamesleeon/LiteGate/releases) [](SECURITY.md) <p align="center"> <img src="./assets/dashboard.png" alt="LiteGate Portal Dashboard" width="100%" style="max-width: 800px; border-radius: 12px; box-shadow: 0 8px 30px rgba(0,0,0,0.3);" /> </p> English | [中文](README_zh.md) LiteGate is a dynamic gateway for private-cloud, VPS, and SaaS entry scenarios. It brings Caddy-style site serving and Traefik-style dynamic backends into one gateway model, so static sites, APIs, certificates, service discovery, and identity-aware entry flow can evolve together instead of being split across multiple components. LiteGate now supports two site configuration modes: - `Lite mode`: minimal `*.lite.yaml` files for fast site bring-up - `Full mode`: standard YAML for complete routing, discovery, and governance features ## Why LiteGate LiteGate is a good fit if you are already using Caddy, or Caddy plus another dynamic routing/discovery layer, and you want to reduce split responsibilities at the edge. It is especially useful when you need some of the following at the same time: - Static sites and backend APIs under one routing model - Automatic HTTPS and DNS-driven certificate workflows - Fixed upstreams first, then service discovery later - Docker-friendly deployment without adopting a full Kubernetes stack - SaaS entry behavior such as remote auth, tenant context injection, or `sid`-based route selection It is less suitable if you only need a basic static site server and have no discovery, identity, or multi-entry requirements. ## Core Advantages - One routing model for static files, fixed upstreams, and discovered backends - Lightweight deployment: single binary, local files, or Docker - Built-in certificate automation, including DNS-based flows and on-demand TLS - Discovery support for `static`, `consul`, `litemesh`, `external`, and `hybrid` - IDS-aware middleware flow for SaaS-style entry decisions > [!IMPORTANT] > **Go Toolchain Requirement:** > LiteGate is built and optimized with **Go 1.26+**. If you build from source, please ensure your local Go toolchain is updated to at least **Go 1.26** to prevent compilation failures caused by modern language features and toolchain constraints. ## Quick Start For the fastest possible first run, you can start a temporary demo site with no config file at all: ```bash ./litegate -hello ``` If you prefer to configure via file, the shortest path is to use **Lite Mode** (`.lite.yaml`) to return a response directly. Create `sites/hello.lite.yaml`: ```yaml localhost: respond: "Hello, LiteGate!" ``` Then run: ```bash mkdir -p sites ./litegate curl http://localhost/ ``` Expected response: ```text Hello, LiteGate! ``` LiteGate listens on `:80` by default. If that port is already in use, adjust your listener configuration first. ## A More Realistic Site This example serves a frontend (SPA) and proxies `/api` to a backend service. Using **Lite Mode**, the configuration is incredibly concise: Create `sites/app.example.com.lite.yaml`: ```yaml app.example.com: /: root: ./dist spa: true /api: proxy: 127.0.0.1:8080 ``` With just a few lines, LiteGate automatically handles route matching and enables HTTPS redirection by default. When your system grows and you need advanced matchers, dynamic service discovery (Consul/Litemesh), load balancing, or identity governance, you can seamlessly transition to the **Full Mode** (standard `.yaml`). ## Build from Source (Super Simple!) You don't need to manually configure complex environment variables or copy tedious `go build` commands for different operating systems. We have provided a powerful, cross-platform **one-click compilation** mechanism. Simply clone the repository and run: ```bash # Clone the repository git clone https://github.com/jamesleeon/LiteGate.git cd LiteGate # Build binaries for ALL 5 platforms (Windows, Linux, macOS) in ONE click! make ``` All compiled binaries will be neatly generated inside the `cmd/bin/` directory instantly! ## Docker This repository already includes a `Dockerfile` and `docker-compose.yaml`. ```bash docker compose up -d ``` The default mounts are: - `./config.yaml:/app/config.yaml` - `./sites:/app/sites` - `./certs:/app/certs` That keeps the local-file workflow and the container workflow aligned. ## Built-in MCP Server (AI Autopilot) LiteGate features a built-in **Model Context Protocol (MCP) Server**, turning the gateway into an AI-agent-friendly infrastructure. When you work with AI agents (e.g., Cline, Cursor, Roo-Code), they can leverage this native protocol to explore environments, validate site configurations, hot-reload rules, and fetch recent errors dynamically. ### How to Enable In your `config.yaml`, simply toggle the `mcp` block: ```yaml mcp: enabled: true port: 8080 # The SSE port the MCP server will listen on ``` ### Connect Your AI Agent To allow your AI Assistant (e.g., **Cline** or **Roo-Code**) to auto-manage LiteGate, add the following configuration to your `mcp_settings.json` (typically located in `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\mcp_settings.json`): ```json { "mcpServers": { "litegate-autopilot": { "type": "sse", "url": "http://127.0.0.1:8080/mcp/sse" } } } ``` Once connected, your AI Agent will have a rich toolset (e.g., `list_sites`, `create_proxy_site`, `reload_gateway`, `get_recent_errors`, `get_kv`, `set_kv`) to help you deploy, upgrade, and troubleshoot sites without you writing a single line of YAML manually! See the [MCP Capability Matrix](docs/en/litegate_mcp_capability_matrix.md) for the complete list of available tools. ## Documentation The documentation is organized by user roles. See the complete [Documentation Hub](docs/en/README.md) for details. **For Users & Operators** (Getting things done quickly): - ⚡ [Lite Quick Start](docs/en/litegate_lite_quickstart.md) - Fastest path to get online. - 📖 [User Guide Index](docs/en/user/README.md) - Full manual covering sites, routes, actions, and certs. **For Architects & Core Developers** (Deep diving & integration): - 🧠 [Architecture White Paper](docs/en/ARCHITECTURE_WHITE_PAPER.md) - 🔀 [L7 Execution Flow](docs/en/l7_execution_flow.md) - How requests traverse the gateway. - 🏷️ [Tag System Guide](docs/en/tag_system_v6_guide.md) - The core of dynamic routing. - 🛡️ [IDS Development Guide](docs/en/ids_development_guide.md) - Extending auth and security. **Project Resources**: - [Roadmap](ROADMAP.md) - [Changelog](CHANGELOG.md) - [Contributing](CONTRIBUTING.md) - [Security Policy](SECURITY.md) ## Project Scope LiteGate is the open-source entry point of a broader infrastructure direction, but this repository focuses on the gateway itself. The main story here is simple: - serve sites - proxy APIs - automate certificates - connect discovery sources - keep edge behavior understandable ## License LiteGate is released under the MIT License. See [LICENSE](LICENSE).