serve.zone/cloudly
2
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

Enhance documentation for @serve.zone/api and @serve.zone/cli

Browse Source 
- Updated the README for @serve.zone/api to improve clarity and organization, adding sections for features, quick start, authentication, core operations, and advanced usage.
- Improved the installation instructions and added examples for various operations including image management, cluster operations, and real-time updates.
- Enhanced the @serve.zone/cli README with a focus on features, installation, quick start, core commands, and advanced usage.
- Added detailed command examples for cluster management, service deployment, secret management, and DNS management.
- Included sections for CI/CD integration and troubleshooting in both README files.
- Improved formatting and added emojis for better readability and engagement.
This commit is contained in:
Jürgen Kunz
2025-08-18 03:14:49 +00:00
parent 907f3e8320
commit 7d4e766e9e
3 changed files with 725 additions and 618 deletions
Download Patch File Download Diff File Expand all files Collapse all files

461
readme.md
View File

@@ -1,335 +1,242 @@
# @serve.zone/cloudly
# @serve.zone/cloudly 🚀
A multi-cloud management tool utilizing Docker Swarmkit for orchestrating containerized apps across various cloud providers, with web, CLI, and API interfaces for configuration and integration management.
**Multi-cloud orchestration made simple.** Manage containerized applications across cloud providers with Docker Swarmkit, featuring web dashboards, CLI tools, and powerful APIs.
## Install
## 🎯 What is Cloudly?
To install `@serve.zone/cloudly`, run the following command in your terminal:
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
npm install @serve.zone/cloudly --save
# 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
```
This will install the package and add it to your project's `package.json` dependencies.
## Usage
`@serve.zone/cloudly` is designed to provide a unified interface for managing multi-cloud environments, encapsulating complex cloud interactions with Docker Swarmkit into simpler, programmable entities. This document will guide you through various use-cases and implementation examples to give you a comprehensive understanding of the module's capabilities.
### Prerequisites
Before you begin, ensure your environment is set up correctly:
- You have Node.js installed (preferably the latest LTS version).
- Your environment is configured to use TypeScript if you're working in a TypeScript project.
### Basic Setup
#### Creating a Cloudly Instance
The foundation of working with `@serve.zone/cloudly` involves creating an instance of the `Cloudly` class. This instance serves as the gateway to managing cloud resources and orchestrates interactions within the platform. Here’s how to get started:
```typescript
import { Cloudly, ICloudlyConfig } from '@serve.zone/cloudly';
const myCloudlyConfig: ICloudlyConfig = {
cfToken: 'your_cloudflare_api_token',
hetznerToken: 'your_hetzner_api_token',
environment: 'development',
letsEncryptEmail: 'lets_encrypt_email@example.com',
publicUrl: 'example.com',
publicPort: '8443',
mongoDescriptor: {
mongoDbUrl: 'mongodb+srv://<username>:<password>@<cluster>.mongodb.net/myFirstDatabase',
mongoDbName: 'myDatabase',
mongoDbUser: 'myUser',
mongoDbPass: 'myPassword',
},
};
const myCloudlyInstance = new Cloudly(myCloudlyConfig);
```
The configuration object `ICloudlyConfig` provides essential information needed for initializing external services, such as Cloudflare, Hetzner, and a MongoDB server. Adjust the parameters to match your actual service credentials and specifications.
### Core Features and Use Cases
#### Orchestrating Docker Swarmkit Clusters
Docker Swarmkit cluster management is a primary feature of `@serve.zone/cloudly`. Through its abstracted, programmable interface, you can operate clusters effortlessly. Here’s an example of how to create a cluster using `Cloudly`:
```typescript
import { Cloudly } from '@serve.zone/cloudly';
interface ICluster {
name: string;
id: string;
cloudlyUrl: string;
servers: string[];
sshKeys: string[];
}
// 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,
}
});
async function manageClusters() {
const myCloudlyConfig = {
cfToken: 'your_cloudflare_api_token',
environment: 'development',
mongoDescriptor: {
mongoDbUrl: 'mongodb+srv://<username>:<password>@<cluster>.mongodb.net/myFirstDatabase',
mongoDbName: 'myDatabase',
mongoDbUser: 'myUser',
mongoDbPass: 'myPassword',
},
letsEncryptEmail: 'lets_encrypt_email@example.com',
publicUrl: 'example.com',
publicPort: 8443,
hetznerToken: 'your_hetzner_api_token',
};
const myCloudlyInstance = new Cloudly(myCloudlyConfig);
await myCloudlyInstance.start();
const newCluster: ICluster = {
name: 'example_cluster',
id: 'example_cluster_id',
cloudlyUrl: 'https://example.com:8443',
servers: [],
sshKeys: [],
};
// Store the newly created cluster with Cloudly
const storedCluster = await myCloudlyInstance.clusterManager.storeCluster(newCluster);
console.log('Cluster stored:', storedCluster);
}
manageClusters();
// Start the platform
await cloudly.start();
console.log('🎉 Cloudly is running!');
```
In this scenario, a cluster called `example_cluster` is initialized using the `Cloudly` instance. This method represents a central mechanism to efficiently handle cluster entities and associated metadata.
## 🏗️ Architecture
#### Integrating With Cloudflare for DNS Management
Cloudly follows a modular architecture with clear separation of concerns:
`@serve.zone/cloudly` provides built-in capabilities for managing DNS records through integration with Cloudflare. Using the `CloudflareConnector`, you can programmatically create, manage, and delete DNS entries:
```
┌─────────────────────────────────────────────┐
│ 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
import { Cloudly } from '@serve.zone/cloudly';
// Create a new cluster
const cluster = await cloudly.clusterManager.createCluster({
name: 'production-cluster',
region: 'eu-central',
nodeCount: 3
});
async function configureCloudflareDNS() {
const myCloudlyConfig = {
cfToken: 'your_cloudflare_api_token',
environment: 'development',
letsEncryptEmail: 'lets_encrypt_email@example.com',
publicUrl: 'example.com',
publicPort: 8443,
hetznerToken: 'your_hetzner_api_token',
mongoDescriptor: {
mongoDbUrl: 'mongodb+srv://<username>:<password>@<cluster>.mongodb.net/myFirstDatabase',
mongoDbName: 'myDatabase',
mongoDbUser: 'myUser',
mongoDbPass: 'myPassword',
},
};
const myCloudlyInstance = new Cloudly(myCloudlyConfig);
await myCloudlyInstance.start();
const cfConnector = myCloudlyInstance.cloudflareConnector.cloudflare;
const dnsRecord = await cfConnector.createDNSRecord('example.com', 'sub.example.com', 'A', '127.0.0.1');
console.log('DNS Record:', dnsRecord);
}
configureCloudflareDNS();
// Deploy a service
await cluster.deployService({
name: 'api-service',
image: 'myapp:latest',
replicas: 3,
ports: [{ published: 80, target: 3000 }]
});
```
Here, you create an A record for the subdomain `sub.example.com` pointing to `127.0.0.1`. All communication with Cloudflare is handled directly through the interface without manual intervention.
#### Dynamic Interaction with DigitalOcean
DigitalOcean resource management, including droplet creation, is simplified in Cloudly. By extending the API to encapsulate calls to external providers, Cloudly provides a seamless experience:
### Secret Management
```typescript
import { Cloudly } from '@serve.zone/cloudly';
// 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 }
]
});
async function createDigitalOceanDroplets() {
const myCloudlyConfig = {
cfToken: 'your_cloudflare_api_token',
environment: 'development',
letsEncryptEmail: 'lets_encrypt_email@example.com',
publicUrl: 'example.com',
publicPort: 8443,
hetznerToken: 'your_hetzner_api_token',
mongoDescriptor: {
mongoDbUrl: 'mongodb+srv://<username>:<password>@<cluster>.mongodb.net/myFirstDatabase',
mongoDbName: 'myDatabase',
mongoDbUser: 'myUser',
mongoDbPass: 'myPassword',
},
};
const myCloudlyInstance = new Cloudly(myCloudlyConfig);
await myCloudlyInstance.start();
const doConnector = myCloudlyInstance.digitaloceanConnector;
const droplet = await doConnector.createDroplet('example-droplet', 'nyc3', 's-1vcpu-1gb', 'ubuntu-20-04-x64');
console.log('Droplet created:', droplet);
}
createDigitalOceanDroplets();
// Create a bundle for deployment
const bundle = await cloudly.secretManager.createSecretBundle({
name: 'production-secrets',
secretGroups: [secretGroup]
});
```
In this script, a droplet named `example-droplet` is created within the `nyc3` region using the `ubuntu-20-04-x64` image. The module abstracts complexities by directly interfacing with DigitalOcean.
### DNS Management
### Advanced Use Cases
```typescript
// Create DNS records via Cloudflare
const record = await cloudly.cloudflareConnector.createDNSRecord(
'example.com',
'api.example.com',
'A',
'192.168.1.1'
);
```
#### Implementing Web Management Interface
`@serve.zone/cloudly` facilitates dashboard management with advanced Web Components built with `@design.estate`. This section of the library allows the creation of dynamic, interactive panels for real-time resource management in a modern browser interface.
### Web Dashboard
```typescript
import { html } from '@design.estate/dees-element';
const renderDashboard = () => {
return html`
<cloudly-dashboard>
<dees-simple-appdash>
<!-- Define sections and elements -->
<cloudly-view-clusters></cloudly-view-clusters>
<cloudly-view-dns></cloudly-view-dns>
<cloudly-view-images></cloudly-view-images>
<!-- Other custom views -->
</dees-simple-appdash>
</cloudly-dashboard>
`;
};
// Create a custom dashboard view
const dashboard = html`
<cloudly-dashboard>
<cloudly-view-clusters></cloudly-view-clusters>
<cloudly-view-dns></cloudly-view-dns>
<cloudly-view-images></cloudly-view-images>
</cloudly-dashboard>
`;
document.body.appendChild(renderDashboard());
document.body.appendChild(dashboard);
```
Utilizing the custom web components designed specifically for Cloudly, dashboards are adaptable, interactive, and maintainable. These elements allow you to structure a complete cloud management center without needing to delve into detailed UI engineering.
## 🛠️ CLI Usage
#### Comprehensive Log Management
The CLI provides quick access to all Cloudly features:
With Cloudly’s Log Management capabilities, you can track and analyze system logs for better insights into your cloud ecosystem’s behavior:
```bash
# Login to your Cloudly instance
servezone login --url https://cloudly.example.com
```typescript
import { Cloudly } from '@serve.zone/cloudly';
# List clusters
servezone clusters list
async function initiateLogManagement() {
const myCloudlyConfig = {
cfToken: 'your_cloudflare_api_token',
environment: 'development',
letsEncryptEmail: 'lets_encrypt_email@example.com',
publicUrl: 'example.com',
publicPort: 8443,
hetznerToken: 'your_hetzner_api_token',
mongoDescriptor: {
mongoDbUrl: 'mongodb+srv://<username>:<password>@<cluster>.mongodb.net/myFirstDatabase',
mongoDbName: 'myDatabase',
mongoDbUser: 'myUser',
mongoDbPass: 'myPassword',
},
};
# Deploy a service
servezone deploy --cluster prod --image myapp:latest
const myCloudlyInstance = new Cloudly(myCloudlyConfig);
await myCloudlyInstance.start();
# Manage secrets
servezone secrets create --name api-key --value "secret123"
const logs = await myCloudlyInstance.logManager.fetchLogs();
console.log('Logs:', logs);
}
initiateLogManagement();
# View logs
servezone logs --service api-service --follow
```
Cloudly provides the tools needed to collect and process logs within your cloud infrastructure. Logs are an essential part of system validation, troubleshooting, monitoring, and auditing.
## 📦 Package Exports
#### Secret Management and Bundles
This monorepo publishes multiple packages:
Managing secrets securely and efficiently is critical for cloud operations. Cloudly allows you to create and manage secret groups and bundles that can be used across multiple applications and environments:
- **@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
```typescript
import { Cloudly } from '@serve.zone/cloudly';
## 🔒 Security Features
async function createSecrets() {
const myCloudlyConfig = {
cfToken: 'your_cloudflare_api_token',
environment: 'development',
letsEncryptEmail: 'lets_encrypt_email@example.com',
publicUrl: 'example.com',
publicPort: 8443,
hetznerToken: 'your_hetzner_api_token',
mongoDescriptor: {
mongoDbUrl: 'mongodb+srv://<username>:<password>@<cluster>.mongodb.net/myFirstDatabase',
mongoDbName: 'myDatabase',
mongoDbUser: 'myUser',
mongoDbPass: 'myPassword',
},
};
- **End-to-end encryption** for secrets
- **Role-based access control** (RBAC)
- **Automatic SSL/TLS** certificate management
- **Secure token-based authentication**
- **Audit logging** for compliance
const myCloudlyInstance = new Cloudly(myCloudlyConfig);
await myCloudlyInstance.start();
## 🚢 Production Ready
const newSecretGroup = await myCloudlyInstance.secretManager.createSecretGroup({
name: 'example_secret_group',
secrets: [
{ key: 'SECRET_KEY', value: 's3cr3t' },
],
});
Cloudly is battle-tested in production environments managing:
- High-traffic web applications
- Microservice architectures
- CI/CD pipelines
- Data processing workloads
- Real-time communication systems
const newSecretBundle = await myCloudlyInstance.secretManager.createSecretBundle({
name: 'example_bundle',
secretGroups: [newSecretGroup],
});
## 🤝 Development
console.log('Created Secret Group and Bundle:', newSecretGroup, newSecretBundle);
}
```bash
# Clone the repository
git clone https://gitlab.com/servezone/private/cloudly.git
createSecrets();
# Install dependencies
pnpm install
# Run tests
pnpm test
# Build the project
pnpm build
# Start development mode
pnpm watch
```
Secrets, such as API keys and sensitive configuration data, are managed efficiently using secret groups and bundles. This structured approach to secret management enhances both security and accessibility.
## 📖 Documentation
### Task Scheduling and Management
With task buffers, you can schedule and manage background tasks integral to cloud operations:
```typescript
import { Cloudly } from '@serve.zone/cloudly';
import { TaskBuffer } from '@push.rocks/taskbuffer';
async function scheduleTasks() {
const myCloudlyConfig = {
cfToken: 'your_cloudflare_api_token',
environment: 'development',
letsEncryptEmail: 'lets_encrypt_email@example.com',
publicUrl: 'example.com',
publicPort: 8443,
hetznerToken: 'your_hetzner_api_token',
mongoDescriptor: {
mongoDbUrl: 'mongodb+srv://<username>:<password>@<cluster>.mongodb.net/myFirstDatabase',
mongoDbName: 'myDatabase',
mongoDbUser: 'myUser',
mongoDbPass: 'myPassword',
},
};
const myCloudlyInstance = new Cloudly(myCloudlyConfig);
await myCloudlyInstance.start();
const taskManager = new TaskBuffer();
taskManager.scheduleEvery('minute', async () => {
console.log('Running scheduled task...');
// Task logic
});
console.log('Tasks scheduled.');
}
scheduleTasks();
```
The example demonstrates setting up periodic task execution using task buffers as part of Cloudly's task management. Whether it's maintenance routines, data updates, or resource checks, tasks can be managed effectively.
This comprehensive overview of `@serve.zone/cloudly` is designed to help you leverage its full capabilities in managing multi-cloud environments. Each example is meant to serve as a starting point, and you are encouraged to explore further by consulting the relevant sections in the documentation, engaging with community discussions, or experimenting in your own environment.
For detailed documentation, API references, and guides, visit our [documentation site](https://cloudly.serve.zone).
## License and Legal Information
@@ -348,4 +255,4 @@ 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.
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.