warren

module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 12, 2025 License: Apache-2.0

README

Warren - Simple Container Orchestrator for Edge

Go Version License Build Status Go Report Card

Warren: Simple like Docker Swarm, feature-rich like Kubernetes, zero external dependencies.

Warren is a container orchestration platform built for edge computing with telco-grade reliability. Delivered as a single binary (< 100MB) with built-in HA, secrets, metrics, ingress controller, and encrypted networking.

✨ Why Warren?

  • 🚀 Simple to Deploy: Single binary, zero config, production-ready in 5 minutes
  • 🔒 Secure by Default: AES-256-GCM secrets, automatic Let's Encrypt, mTLS ready
  • 🌍 Edge-Optimized: Fast failover (2-3s), partition tolerance, low resource usage
  • 📦 Feature-Complete: Rolling updates, secrets, volumes, HA, ingress, metrics—all built-in
  • ⚡ High Performance: 10 svc/s creation, 10,000 req/s ingress, < 256MB memory
  • 🤝 Open Source: Apache 2.0, active development, welcoming community

🎯 Use Cases

  • Edge Computing: Deploy at cell towers, IoT gateways, retail locations
  • Small Teams: Production orchestration without Kubernetes complexity
  • Multi-Site: Distributed deployments across geographic locations
  • Migration: Drop-in replacement for Docker Swarm (now closed-source)

🚀 Quick Start

Installation

Homebrew (macOS):

brew install cuemby/tap/warren

APT (Debian/Ubuntu):

curl -sL https://packagecloud.io/cuemby/warren/gpgkey | sudo apt-key add -
echo "deb https://packagecloud.io/cuemby/warren/ubuntu/ focal main" | sudo tee /etc/apt/sources.list.d/warren.list
sudo apt update && sudo apt install warren

Binary Download:

# Linux AMD64
curl -LO https://github.com/cuemby/warren/releases/latest/download/warren-linux-amd64.tar.gz
tar xzf warren-linux-amd64.tar.gz
sudo mv warren /usr/local/bin/

From Source:

git clone https://github.com/cuemby/warren.git
cd warren
make build
sudo make install
macOS Support

Warren uses Lima VM to provide seamless container orchestration on macOS:

# Install Lima (if not already installed)
brew install lima

# Warren will automatically manage Lima VM
sudo warren cluster init

# Lima VM starts automatically, no manual setup needed!

Warren automatically creates and manages a lightweight Linux VM (Alpine-based) with containerd. The Lima VM is stopped gracefully when Warren shuts down.

Deploy Your First Service (with HTTPS!)
# 1. Initialize cluster
sudo warren cluster init

# 2. Start worker (in another terminal)
sudo warren worker start --manager 127.0.0.1:8080

# 3. Deploy nginx with health checks
warren service create nginx \
  --image nginx:latest \
  --replicas 3 \
  --port 80 \
  --health-http / \
  --health-interval 30 \
  --manager 127.0.0.1:8080

# 4. Create HTTPS ingress with automatic Let's Encrypt
warren ingress create my-ingress \
  --host myapp.example.com \
  --service nginx \
  --port 80 \
  --tls \
  --tls-email admin@example.com \
  --manager 127.0.0.1:8080

# 5. Check status
warren service list --manager 127.0.0.1:8080
warren ingress list --manager 127.0.0.1:8080

That's it! You have a production-ready orchestrator with HTTPS routing and automatic certificate management.

📚 Documentation

Essential Guides:

Concepts:

Migration:

Community:

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                   Warren Cluster                         │
│                                                           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │  Manager 1   │  │  Manager 2   │  │  Manager 3   │  │
│  │  (Leader)    │◄─┤  (Follower)  │◄─┤  (Follower)  │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         │                 │                 │            │
│         │      Raft Consensus (State)       │            │
│         │                                    │            │
│         └─────────────┬────────────────────┘            │
│                       │                                   │
│          WireGuard Encrypted Overlay                     │
│                       │                                   │
│       ┌───────────────┴───────────────┐                 │
│       │                                │                 │
│  ┌────▼─────┐                    ┌────▼─────┐          │
│  │ Worker 1 │                    │ Worker 2 │          │
│  │          │                    │          │          │
│  │ [nginx]  │                    │ [redis]  │          │
│  │ [api]    │                    │ [db]     │          │
│  └──────────┘                    └──────────┘          │
└─────────────────────────────────────────────────────────┘

Key Components:

  • Managers: Raft consensus, state storage (BoltDB), API server, scheduler, reconciler, ingress controller
  • Workers: Task execution (containerd), heartbeat, local state cache
  • Networking: DNS service discovery, WireGuard mesh, service VIPs, HTTP/HTTPS ingress
  • Storage: Encrypted secrets (AES-256-GCM), local volumes, BoltDB state

⚡ Features

Core Orchestration
  • ✅ Multi-manager HA (Raft consensus)
  • ✅ Auto-scaling and self-healing
  • ✅ Health checks (HTTP, TCP, Exec)
  • ✅ DNS service discovery
  • ✅ Global services (DaemonSet equivalent)
Networking & Ingress 🆕
  • ✅ HTTP/HTTPS ingress controller (no nginx/traefik needed!)
  • ✅ Let's Encrypt integration (automatic certificates)
  • ✅ Host & path-based routing
  • ✅ Load balancing with health checks
  • ✅ Advanced routing (rate limiting, access control, headers, path rewriting)
  • ✅ TLS certificate management
Deployment
  • ✅ Rolling updates (zero downtime)
  • ✅ Resource limits (CPU/memory)
  • ✅ Graceful shutdown
  • ✅ Published ports
  • ✅ YAML declarative config
Security
  • ✅ Encrypted secrets (AES-256-GCM)
  • ✅ mTLS for gRPC
  • ✅ Automatic TLS certificates
  • ✅ IP-based access control
  • ✅ WireGuard encrypted overlay (planned M8)
Storage
  • ✅ Local volumes with node affinity
  • ✅ Automatic volume management
  • ✅ Distributed drivers (NFS, Ceph - M8)
Observability
  • ✅ Prometheus metrics (/metrics)
  • ✅ Structured logging (JSON + zerolog)
  • ✅ Event streaming (foundation)
  • ✅ Profiling support (pprof)
Developer Experience
  • ✅ Single binary (< 100MB)
  • ✅ Comprehensive CLI
  • ✅ Shell completion (bash, zsh, fish)
  • ✅ YAML apply support

📊 Performance

Validated on 3-node cluster (1 manager, 2 workers):

Metric Target Actual
Service creation > 1 svc/s 10 svc/s ✅
Ingress throughput > 5,000 req/s 10,000 req/s ✅ 🆕
API latency < 100ms 66ms ✅
Binary size < 100MB 80MB ✅
Manager memory < 256MB ~200MB ✅
Worker memory < 128MB ~100MB ✅
Failover time < 10s 2-3s ✅

🗺️ Roadmap

✅ Milestone 0: Foundation (Complete)
  • POCs (Raft, containerd, WireGuard)
  • Architecture Decision Records
✅ Milestone 1: Core Orchestration (Complete)
  • Single-manager cluster, scheduler, reconciler
  • Worker agent with heartbeat
  • gRPC API, full CLI
✅ Milestone 2: High Availability (Complete)
  • Multi-manager Raft cluster
  • Leader election & failover
  • Containerd integration
✅ Milestone 3: Advanced Deployment (Complete)
  • Secrets management (AES-256-GCM)
  • Volume orchestration
  • Global services
  • Deployment strategies foundation
✅ Milestone 4: Observability (Complete)
  • Prometheus metrics
  • Structured logging
  • Multi-platform builds
  • Performance tuning
✅ Milestone 5: Open Source (Complete)
  • Documentation (14 guides)
  • CI/CD automation
  • Package distribution
  • Community infrastructure
✅ Milestone 6: Production Hardening (Complete)
  • mTLS for gRPC
  • Health checks (HTTP, TCP, Exec)
  • Published ports with conflict detection
  • Resource limits (CPU/memory)
  • DNS service discovery
  • Graceful shutdown
✅ Milestone 7: Built-in Ingress (Complete) 🆕
  • HTTP/HTTPS ingress controller
  • Let's Encrypt ACME integration
  • Host & path-based routing
  • Load balancing with health checks
  • Advanced routing (rate limiting, access control, headers, path rewriting)
  • TLS certificate management
🔜 Milestone 8: Advanced Features (Next)
  • WireGuard encrypted overlay
  • Distributed volume drivers (NFS, Ceph)
  • Network policies
  • Blue/green & canary deployment
  • Custom schedulers

🤝 Contributing

We welcome contributions! Warren is a community-driven project.

Getting Started:

  1. Read CONTRIBUTING.md
  2. Check good first issues
  3. Join GitHub Discussions

Ways to Contribute:

  • 🐛 Report bugs
  • 💡 Suggest features
  • 📝 Improve documentation
  • 🧪 Add tests
  • 💻 Submit code

Development:

# Clone repository
git clone https://github.com/cuemby/warren.git
cd warren

# Build
make build

# Run tests
go test ./...

# Run linter
golangci-lint run

🆚 Comparison

Feature Warren Docker Swarm Kubernetes
Setup Time < 5 min < 5 min 30+ min
Binary Size 80MB 50MB N/A (distributed)
Manager Memory 256MB 200MB 2GB+
Built-in HA ✅ ✅ ✅
Built-in Secrets ✅ ✅ ✅
Built-in Metrics ✅ ❌ ❌ (add-on)
Built-in Ingress ✅ 🆕 ❌ ❌ (add-on)
Let's Encrypt ✅ 🆕 ❌ ❌ (add-on)
Edge Optimized ✅ ❌ ❌
Open Source ✅ ❌ (closed) ✅
Failover Time 2-3s 10-15s 30-60s

Warren = Swarm simplicity + K8s features - K8s complexity

📖 Project Structure

warren/
├── cmd/warren/              # CLI entry point
├── pkg/
│   ├── manager/             # Manager (Raft, scheduler, reconciler)
│   ├── worker/              # Worker agent
│   ├── api/                 # gRPC API server
│   ├── scheduler/           # Task scheduler
│   ├── reconciler/          # Desired state reconciler
│   ├── ingress/             # HTTP/HTTPS ingress controller 🆕
│   ├── security/            # Secrets encryption
│   ├── volume/              # Volume orchestration
│   ├── events/              # Event streaming
│   └── types/               # Core data models
├── api/proto/               # Protobuf definitions
├── docs/                    # Documentation
├── test/                    # Integration tests
├── packaging/               # Homebrew, APT setup
└── .github/workflows/       # CI/CD automation

🙏 Acknowledgments

Warren is inspired by:

  • Docker Swarm - Simplicity of UX
  • Kubernetes - Feature richness
  • Nomad - Single binary distribution

Built with:

📝 License

Apache 2.0 - See LICENSE for details.

Copyright 2025 Cuemby Inc.

💬 Community

🎉 Status

Current Release: v1.1.0 (Milestone 7 Complete) 🆕

Warren is production-ready for edge deployments with:

  • ✅ Multi-manager HA validated
  • ✅ 10,000+ tasks tested
  • ✅ Built-in HTTPS ingress with Let's Encrypt 🆕
  • ✅ 100-node clusters validated
  • ✅ Comprehensive documentation
  • ✅ Automated CI/CD
  • ✅ Package distribution

Deploy with HTTPS in 3 commands! 🚀

Maintained by: Cuemby 🐰 | Status: Production Ready ✅

Directories

Path Synopsis
api
proto
cmd
warren command
pkg
api
client
deploy
dns
embedded
events
health
ingress
log
manager
metrics
network
reconciler
runtime
scheduler
security
storage
types
volume
worker

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.