# Uncloud — Lightweight Container Orchestration Across Docker Hosts

> A lightweight tool for deploying and managing containerized applications across a network of Docker hosts. Bridges the gap between Docker Compose and Kubernetes, providing multi-host orchestration without the complexity.

## Install

Save in your project root:

# Uncloud — Lightweight Container Orchestration Across Docker Hosts

## Quick Use
```bash
# Install Uncloud
curl -fsSL https://get.uncloud.run | sh
# Initialize a cluster on the first machine
uncloud init
# Join additional machines
uncloud join <token>
# Deploy an application
uncloud deploy --name myapp --image nginx:latest --publish 80:80
```

## Introduction
Uncloud is a lightweight container orchestration tool that lets you deploy applications across multiple Docker hosts without the operational overhead of Kubernetes. It provides a simple CLI for managing distributed containers, handling networking, load balancing, and service discovery across a cluster of machines connected via WireGuard.

## What Uncloud Does
- Deploys containers across multiple Docker hosts from a single CLI
- Creates an encrypted WireGuard mesh network between cluster nodes automatically
- Provides built-in load balancing and service discovery for deployed applications
- Supports rolling updates and health checks for zero-downtime deployments
- Manages TLS certificates automatically for exposed services

## Architecture Overview
Uncloud runs a lightweight agent on each Docker host in the cluster. Nodes communicate over a WireGuard mesh network that Uncloud provisions automatically. The CLI sends deployment commands to any node, which schedules containers across the cluster based on available resources. A built-in DNS server handles service discovery, and an integrated reverse proxy routes external traffic to the correct containers. All cluster state is stored in an embedded distributed database.

## Self-Hosting & Configuration
- Install the Uncloud binary on each host via the official install script
- Run ``uncloud init`` on the first node to create the cluster and generate a join token
- Join additional nodes using ``uncloud join <token>``
- Deploy applications with ``uncloud deploy`` specifying image, ports, and replicas
- Configure custom domains and TLS settings for public-facing services

## Key Features
- Zero-config WireGuard networking between cluster nodes
- Single binary with no external dependencies (no etcd, no separate database)
- Docker Compose-like simplicity for multi-host deployments
- Built-in reverse proxy with automatic TLS via Let's Encrypt
- Resource-aware scheduling across heterogeneous machines

## Comparison with Similar Tools
- **Kubernetes** — Full orchestration platform with steep learning curve; Uncloud targets small-to-medium deployments with minimal setup
- **Docker Swarm** — Docker's built-in orchestration (deprecated features); Uncloud offers WireGuard networking and simpler UX
- **Nomad** — HashiCorp's workload orchestrator; Uncloud is lighter with fewer moving parts
- **Kamal** — Deploy Rails apps via SSH; Uncloud provides a persistent cluster with networking and service discovery

## FAQ
**Q: How many nodes can Uncloud handle?**
A: Uncloud is designed for small-to-medium clusters, typically 2-50 nodes. It trades the complexity of large-scale orchestrators for operational simplicity.

**Q: Does Uncloud replace Docker Compose?**
A: Uncloud extends Docker Compose concepts to multiple hosts. You can think of it as Docker Compose with built-in clustering, networking, and load balancing.

**Q: Is WireGuard required?**
A: WireGuard is used automatically for encrypted inter-node communication. Uncloud provisions and manages the WireGuard tunnels — no manual VPN setup needed.

**Q: Can I use my existing Docker images?**
A: Yes. Uncloud deploys standard OCI/Docker images from any registry. No changes to your images or Dockerfiles are needed.

## Sources
- https://github.com/psviderski/uncloud
- https://uncloud.run

---
Source: https://tokrepo.com/en/workflows/40973d14-3b42-11f1-9bc6-00163e2b0d79
Author: AI Open Source