litemesh

# Litemesh [中文文档](README.zh-CN.md) [](https://opensource.org/licenses/Apache-2.0) [](https://goreportcard.com/report/github.com/james/litemesh)  Litemesh is a lightweight, decentralized service discovery and configuration system built on Serf and gossip. It is designed to give distributed applications a simple control plane for service registration, configuration distribution, health checks, and zero-trust mTLS. Litemesh is intentionally not positioned as a strongly consistent lock service. If your workload primarily needs strongly consistent distributed locks or ID segment allocation, use the companion `lockd` project instead. The two projects are complementary rather than overlapping. ## Highlights - Decentralized cluster architecture with no single control node - Real-time change notifications over SSE - Active health checks for HTTP, TCP, gRPC, and TTL-based services - Distributed KV store with CAS, sessions, and lock primitives - Consul-compatible APIs for smoother migration - Built-in SPIFFE-style CA for proxyless mTLS - MCP integration for AI agent infrastructure workflows ## Project Boundary Use Litemesh for: - service discovery - configuration distribution - health checks and change signals - built-in mTLS foundations - lightweight coordination primitives in high-availability environments Use `lockd` for: - strongly consistent distributed locks - strong lock ownership semantics - ID segment allocation and dedicated ID infrastructure ## Quick Start ### 1. Clone & Build Litemesh Clone the repository and build the binary for your platform in one go (using Linux as an example): ```bash # 1. Clone the repository and enter the directory git clone https://github.com/jamesleeon/litemesh.git cd litemesh # 2. Build the binary for your platform (e.g. Linux) make linux # Or make windows / make mac # 3. Enter the output directory to find the application cd cmd/bin/ ./litemesh_linux_amd64 --help ``` Once the compilation succeeds, the target binaries will be generated inside the `cmd/bin/` directory (e.g., `litemesh_linux_amd64` for Linux AMD64). ### 2. Generate configuration template You can instantly generate the latest recommended configuration template using `--init` inside the `cmd/bin/` directory: ```bash ./litemesh_linux_amd64 --init ``` This writes a default `config.example.yaml` in your current directory. To prevent accidental overwriting of your active production settings, `--init` will never write to `config.yaml` directly. ### 3. Run Litemesh Copy the generated template to `config.yaml`, customize it, and start the node: ```bash cp config.example.yaml config.yaml ./cmd/bin/litemesh_linux_amd64 -config config.yaml ``` ### Build binaries Use the repository `Makefile` if you want the compiled binaries to be placed under `cmd/bin/`: ```bash make all ``` Available targets include: - `make all` - Compile binaries for all platforms (Windows, Linux, macOS) - `make windows` - Build for Windows (amd64) - `make linux` - Build for Linux (amd64) - `make arm` - Build for Linux (arm64) - `make mac` - Build for macOS (Intel & Apple Silicon) - `make test` - Run unit tests - `make fmt` - Run go fmt - `make clean` - Clean up build artifacts ### Run via Docker Compose You can instantly spin up Litemesh in a containerized environment: ```bash cp config.example.yaml config.yaml docker-compose up -d ``` ### Register a service ```bash curl -X PUT http://localhost:8080/v1/agent/service/register \ -H "Content-Type: application/json" \ -d '{ "ID": "web-1", "Name": "web-service", "Address": "127.0.0.1", "Port": 8080 }' ``` ## Documentation Start with the docs hub at [docs/en/README.md](docs/en/README.md). Chinese readers can start with [README.zh-CN.md](README.zh-CN.md) or [docs/zh-CN/README.md](docs/zh-CN/README.md). - [Quick Start](docs/en/quickstart.md) - [Usage & Integration](docs/en/usage.md) - [Client Integration Best Practices](docs/en/client_best_practices.md) - [KV & Distributed Tasks](docs/en/kv_and_tasks.md) - [Security & mTLS](docs/en/security.md) - [Architecture & Internals](docs/en/architecture.md) ## Contributing Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. Please also review [SECURITY.md](SECURITY.md) for vulnerability reporting and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community expectations. ## License This project is licensed under [Apache-2.0](LICENSE).