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

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:

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:

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:

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:

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.

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:

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:

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:

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