# @serve.zone/cloudly πŸš€ **Multi-cloud orchestration made simple.** Manage containerized applications across cloud providers with Docker Swarmkit, featuring web dashboards, CLI tools, and powerful APIs. ## 🎯 What is Cloudly? Cloudly is your command center for multi-cloud infrastructure. It abstracts away the complexity of managing resources across different cloud providers while giving you the power and flexibility you need for modern DevOps workflows. ### ✨ Key Features - **🌐 Multi-Cloud Management** - Seamlessly orchestrate resources across Cloudflare, Hetzner, DigitalOcean and more - **🐳 Docker Swarmkit Integration** - Native container orchestration with production-grade reliability - **πŸ” Secret Management** - Secure handling of credentials, API keys, and sensitive configuration - **🎨 Web Dashboard** - Beautiful, responsive UI built with modern web components - **⚑ CLI & API** - Full programmatic control through TypeScript/JavaScript APIs and command-line tools - **πŸ”’ SSL/TLS Automation** - Automatic certificate provisioning via Let's Encrypt - **πŸ“Š Comprehensive Logging** - Built-in log aggregation and monitoring capabilities - **πŸ”„ Task Scheduling** - Automated workflows and background job management ## πŸš€ Quick Start ### Installation ```bash # Install the main package pnpm add @serve.zone/cloudly # Or install the CLI globally pnpm add -g @serve.zone/cli # Or just the API client pnpm add @serve.zone/api ``` ### Basic Setup ```typescript import { Cloudly } from '@serve.zone/cloudly'; // Initialize Cloudly with your configuration const cloudly = new Cloudly({ cfToken: process.env.CLOUDFLARE_TOKEN, hetznerToken: process.env.HETZNER_TOKEN, environment: 'production', letsEncryptEmail: 'certs@example.com', publicUrl: 'cloudly.example.com', publicPort: 443, mongoDescriptor: { mongoDbUrl: process.env.MONGODB_URL, mongoDbName: 'cloudly', mongoDbUser: process.env.MONGODB_USER, mongoDbPass: process.env.MONGODB_PASS, } }); // Start the platform await cloudly.start(); console.log('πŸŽ‰ Cloudly is running!'); ``` ## πŸ—οΈ Architecture Cloudly follows a modular architecture with clear separation of concerns: ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Web Dashboard (UI) β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ API Layer (TypedRouter) β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ Core Managers β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚ Cluster β”‚ β”‚ Image β”‚ β”‚ Secret β”‚ ... β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ Cloud Connectors β”‚ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€----┐ β”‚ β”‚ β”‚Cloudflareβ”‚ β”‚ Hetzner β”‚ β”‚ DigitalOcean β”‚ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ └──────────----β”˜ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` ## πŸ’» Core Components ### πŸ”§ Managers - **AuthManager** - Identity and access management - **ClusterManager** - Docker Swarm cluster orchestration - **ImageManager** - Container image lifecycle management - **SecretManager** - Secure credential storage and distribution - **ServerManager** - Cloud server provisioning and management - **TaskManager** - Background job scheduling and execution ### πŸ”Œ Connectors - **CloudflareConnector** - DNS, CDN, and edge services - **LetsencryptConnector** - Automatic SSL certificate provisioning - **MongodbConnector** - Database persistence layer - **HetznerConnector** - German cloud infrastructure - **DigitalOceanConnector** - Developer-friendly cloud resources ## πŸ“š Usage Examples ### Managing Clusters ```typescript // Create a new cluster const cluster = await cloudly.clusterManager.createCluster({ name: 'production-cluster', region: 'eu-central', nodeCount: 3 }); // Deploy a service await cluster.deployService({ name: 'api-service', image: 'myapp:latest', replicas: 3, ports: [{ published: 80, target: 3000 }] }); ``` ### Secret Management ```typescript // Create a secret group const secretGroup = await cloudly.secretManager.createSecretGroup({ name: 'api-credentials', secrets: [ { key: 'API_KEY', value: process.env.API_KEY }, { key: 'DB_PASSWORD', value: process.env.DB_PASSWORD } ] }); // Create a bundle for deployment const bundle = await cloudly.secretManager.createSecretBundle({ name: 'production-secrets', secretGroups: [secretGroup] }); ``` ### DNS Management ```typescript // Create DNS records via Cloudflare const record = await cloudly.cloudflareConnector.createDNSRecord( 'example.com', 'api.example.com', 'A', '192.168.1.1' ); ``` ### Web Dashboard ```typescript import { html } from '@design.estate/dees-element'; // Create a custom dashboard view const dashboard = html` `; document.body.appendChild(dashboard); ``` ## πŸ› οΈ CLI Usage The CLI provides quick access to all Cloudly features: ```bash # Login to your Cloudly instance servezone login --url https://cloudly.example.com # List clusters servezone clusters list # Deploy a service servezone deploy --cluster prod --image myapp:latest # Manage secrets servezone secrets create --name api-key --value "secret123" # View logs servezone logs --service api-service --follow ``` ## πŸ“¦ Package Exports This monorepo publishes multiple packages: - **@serve.zone/cloudly** - Main orchestration platform - **@serve.zone/api** - TypeScript/JavaScript API client - **@serve.zone/cli** - Command-line interface - **@serve.zone/interfaces** - Shared TypeScript interfaces ## πŸ”’ Security Features - **End-to-end encryption** for secrets - **Role-based access control** (RBAC) - **Automatic SSL/TLS** certificate management - **Secure token-based authentication** - **Audit logging** for compliance ## 🚒 Production Ready Cloudly is battle-tested in production environments managing: - High-traffic web applications - Microservice architectures - CI/CD pipelines - Data processing workloads - Real-time communication systems ## 🀝 Development ```bash # Clone the repository git clone https://gitlab.com/servezone/private/cloudly.git # Install dependencies pnpm install # Run tests pnpm test # Build the project pnpm build # Start development mode pnpm watch ``` ## πŸ“– Documentation For detailed documentation, API references, and guides, visit our [documentation site](https://cloudly.serve.zone). ## License and Legal Information This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file. ### Trademarks This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH. ### Company Information Task Venture Capital GmbH Registered at District court Bremen HRB 35230 HB, Germany For any legal inquiries or if you require further information, please contact us via email at hello@task.vc. By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.