cloudly/readme.md

# @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.

## Install

To install `@serve.zone/cloudly`, run the following command in your terminal:

```bash
npm install @serve.zone/cloudly --save
```

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[];
}

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();
```

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.

#### Integrating With Cloudflare for DNS Management

`@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:

```typescript
import { Cloudly } from '@serve.zone/cloudly';

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();
```

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:

```typescript
import { Cloudly } from '@serve.zone/cloudly';

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();
```

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.

### Advanced Use Cases

#### 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.

```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>
    `;
};

document.body.appendChild(renderDashboard());
```

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.

#### Comprehensive Log Management

With Cloudly’s Log Management capabilities, you can track and analyze system logs for better insights into your cloud ecosystem’s behavior:

```typescript
import { Cloudly } from '@serve.zone/cloudly';

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',
        },
    };

    const myCloudlyInstance = new Cloudly(myCloudlyConfig);
    await myCloudlyInstance.start();

    const logs = await myCloudlyInstance.logManager.fetchLogs();
    console.log('Logs:', logs);
}

initiateLogManagement();
```

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.

#### Secret Management and Bundles

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:

```typescript
import { Cloudly } from '@serve.zone/cloudly';

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',
        },
    };

    const myCloudlyInstance = new Cloudly(myCloudlyConfig);
    await myCloudlyInstance.start();

    const newSecretGroup = await myCloudlyInstance.secretManager.createSecretGroup({
        name: 'example_secret_group',
        secrets: [
            { key: 'SECRET_KEY', value: 's3cr3t' },
        ],
    });

    const newSecretBundle = await myCloudlyInstance.secretManager.createSecretBundle({
        name: 'example_bundle',
        secretGroups: [newSecretGroup],
    });

    console.log('Created Secret Group and Bundle:', newSecretGroup, newSecretBundle);
}

createSecrets();
```

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.

### 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.

## 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.