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

500
ts_cliclient/readme.md
View File

@@ -1,246 +1,342 @@
# @serve.zone/cli
# @serve.zone/cli 🚀
A comprehensive command-line interface (CLI) tool for managing multi-cloud environments, leveraging the features of the @serve.zone/cloudly platform. This CLI is crafted to facilitate seamless interactions with complex cloud configurations and deployments, utilizing Docker Swarmkit orchestration.
**Command-line interface for Cloudly.** Manage your multi-cloud infrastructure from the terminal with powerful, intuitive commands.
## Install
## 🎯 What is @serve.zone/cli?
To begin using the `@serve.zone/cli` in your projects, install it via npm by running:
The Cloudly CLI brings the full power of the Cloudly platform to your terminal. Whether you're automating deployments, managing secrets, or monitoring services, the CLI provides a streamlined interface for all your cloud operations.
## ✨ Features
- **⚡ Fast & Efficient** - Optimized for speed and minimal resource usage
- **🔐 Secure Authentication** - Token-based authentication with secure storage
- **📝 Intuitive Commands** - Clear, consistent command structure
- **🎨 Formatted Output** - Beautiful, readable output with color coding
- **🔄 Scriptable** - Perfect for CI/CD pipelines and automation
- **📊 Comprehensive** - Access to all Cloudly features from the terminal
## 🚀 Installation
### Global Installation (Recommended)
```bash
npm install @serve.zone/cli --save
pnpm add -g @serve.zone/cli
```
This command will download the package and integrate it into your project's `node_modules` directory, reflecting the dependency in your `package.json`.
### Local Installation
## Usage
The `@serve.zone/cli` is a powerful command-line tool aimed at developers and system administrators who are managing containerized applications across various cloud platforms. Through this CLI, users can interact with their cloud infrastructure efficiently, enabling and extending `Cloudly’s` capabilities directly from the terminal.
### Prerequisites
Before proceeding to use the `@serve.zone/cli`, ensure your system meets the following prerequisites:
- Latest Node.js LTS version installed.
- Familiarity with basic command-line operations.
- Properly configured cloud service accounts (like Cloudflare, Hetzner), necessary for managing respective services.
### Setting Up the CLI
Begin setting up the `Cloudly` instance for CLI usage:
```typescript
// Import required modules
import { Cloudly } from '@serve.zone/cloudly';
import * as path from 'path';
// Define the configuration needed for cloud operations
const cloudlyConfig = {
cfToken: 'your-cloudflare-token',
hetznerToken: 'your-hetzner-token',
environment: 'production',
publicUrl: 'your-public-url',
};
// Instantiate and start the Cloudly instance
const cloudlyInstance = new Cloudly(cloudlyConfig);
await cloudlyInstance.start();
// Log the setup information to ensure it’s correct
console.log(`Cloudly is set up at ${cloudlyInstance.config.data.publicUrl}`);
```bash
pnpm add @serve.zone/cli
```
This snippet initializes a Cloudly instance with necessary environment configuration, setting the groundwork for all subsequent CLI operations.
## 🎬 Quick Start
### Core Operations with the CLI
```bash
# Configure your Cloudly instance
servezone config --url https://cloudly.example.com
Here's how you leverage various operational commands within the CLI feature:
# Login with your service token
servezone login --token your-service-token
#### Managing Clusters
# List your clusters
servezone clusters list
To create, list, and delete clusters, you’ll require invoking the `Cloudly` class with its cluster management logic:
```typescript
// Module imports
import { Cloudly } from '@serve.zone/cloudly';
// Async function for cluster management
async function manageCluster() {
// Prepare configuration
const config = {
cfToken: 'YOUR_CLOUDFLARE_TOKEN',
hetznerToken: 'YOUR_HETZNER_TOKEN',
};
// Initialize Cloudly
const cloudlyInstance = new Cloudly(config);
await cloudlyInstance.start();
// Example: Creating a new cluster
const cluster = await cloudlyInstance.clusterManager.createCluster({
id: 'example_cluster_id',
data: {
name: 'example_cluster',
servers: [],
sshKeys: [],
}
});
// Log cluster details
console.log('Cluster created:', cluster);
}
```
With the above example, you can dynamically manage cluster configurations, ensuring your application components are effectively orchestrated across cloud environments.
#### Deploying Services
Deploying cloud-native services within your clusters can be achieved through the CLI:
```typescript
import { Cloudly } from '@serve.zone/cloudly';
// Function to handle service deployment
async function deployService() {
const config = {
cfToken: 'YOUR_CLOUDFLARE_TOKEN',
hetznerToken: 'YOUR_HETZNER_TOKEN',
};
const cloudlyInstance = new Cloudly(config);
await cloudlyInstance.start();
// Deploy a new service to a specified cluster
const newService = {
id: 'example_service_id',
data: {
name: 'example_service',
imageId: 'example_image_id',
imageVersion: '1.0.0',
environment: {},
ports: { web: 80 }
}
};
// Store service into database and deploy
console.log('Deploying service:', newService)
await cloudlyInstance.serverManager.deployService(newService);
}
deployService();
# Deploy a service
servezone deploy --cluster production --image myapp:latest
```
By streamlining your service deployments through CLI, you ensure reproducibility and clarity in development operations.
## 🔑 Authentication
#### Managing Certificates
### Initial Setup
Ensuring secure connections by managing SSL certificates is essential. The CLI aids in this through Let's Encrypt integration:
```bash
# Set your Cloudly instance URL
servezone config --url https://cloudly.example.com
```typescript
import { Cloudly } from '@serve.zone/cloudly';
# Authenticate with a service token
servezone login --token YOUR_SERVICE_TOKEN
// Function to acquire a certificate
async function getCertificate() {
const config = {
cfToken: 'YOUR_CLOUDFLARE_TOKEN',
hetznerToken: 'YOUR_HETZNER_TOKEN',
};
const cloudlyInstance = new Cloudly(config);
await cloudlyInstance.start();
// Fetch certificate using Let's Encrypt
const domainName = 'example.com';
const cert = await cloudlyInstance.letsencryptConnector.getCertificateForDomain(domainName);
console.log(`Obtained certificate for domain ${domainName}:`, cert);
}
getCertificate();
# Or use environment variables
export CLOUDLY_URL=https://cloudly.example.com
export CLOUDLY_TOKEN=YOUR_SERVICE_TOKEN
```
This process facilitates the automation of SSL certificates provisioning, ensuring high security in your apps.
### Managing Profiles
### Automating Tasks with the CLI
```bash
# Create a profile for different environments
servezone profile create production --url https://prod.cloudly.com
servezone profile create staging --url https://stage.cloudly.com
Task scheduling is a feature you can utilize to automate recurring processes. Here’s an example of how `@serve.zone/cli` accomplishes task scheduling:
# Switch between profiles
servezone profile use production
```typescript
import { TaskBuffer } from '@push.rocks/taskbuffer';
// Schedule a task to run every day
const dailyTask = new TaskBuffer({
schedule: '0 0 * * *', // Using cron schedule
taskFunction: async () => {
console.log('Performing daily backup check...');
// Include backup logic here
},
});
// Initiate task scheduling
dailyTask.start();
# List all profiles
servezone profile list
```
Scheduled tasks like periodic maintenance, data synchronization, or backups ensure you keep your cloud environment robust and reliable.
## 📚 Core Commands
### Integrating Third-Party APIs
### 🌐 Cluster Management
Expand the scope of your applications with API integrations offered via `@serve.zone/cli`:
```bash
# List all clusters
servezone clusters list
```typescript
import { Cloudly } from '@serve.zone/cloudly';
# Get cluster details
servezone clusters info production-cluster
// Function to send notifications
async function sendNotification() {
const cloudlyConfig = {
cfToken: 'your-cloudflare-token',
hetznerToken: 'your-hetzner-token',
};
# Create a new cluster
servezone clusters create \
--name production-cluster \
--region eu-central \
--nodes 3
const cloudly = new Cloudly(cloudlyConfig);
await cloudly.start();
# Scale a cluster
servezone clusters scale production-cluster --nodes 5
// Configure and send push notification
await cloudly.externalApiManager.sendPushMessage({
deviceToken: 'some_device_token',
message: 'Hello from Cloudly!',
});
}
sendNotification();
# Delete a cluster
servezone clusters delete staging-cluster
```
API integrations via the CLI extend Cloudly’s reach, enabling comprehensive service interconnections.
### 🐳 Service Deployment
### Security and Access Management
```bash
# Deploy a service
servezone deploy \
--cluster production \
--name api-service \
--image myapp:2.0.0 \
--replicas 3 \
--port 80:3000
Effective identity management is possible through `@serve.zone/cli`. Manage user roles, token validations, and more:
# Update a service
servezone service update api-service \
--image myapp:2.1.0 \
--replicas 5
```typescript
import { Cloudly } from '@serve.zone/cloudly';
# Scale a service
servezone service scale api-service --replicas 10
// Configuring and verifying identity
async function authenticateUser() {
const cloudlyConfig = {
cfToken: 'your-cloudflare-token',
hetznerToken: 'your-hetzner-token',
};
const cloudly = new Cloudly(cloudlyConfig);
await cloudly.start();
// Sample user credentials
const userIdentity = {
userId: 'unique_user_id',
jwt: 'user_jwt_token',
};
// Validate identity
const isValid = cloudly.authManager.validateIdentity(userIdentity);
console.log(`Is user identity valid? ${isValid}`);
}
authenticateUser();
# Remove a service
servezone service remove api-service
```
The applications of identity validation streamline operational security and enforce access controls across your systems.
### 🔐 Secret Management
These examples offer a glimpse into the vast potential of @serve.zone/cli, which combines automation, security, and flexibility for state-of-the-art cloud management. You are encouraged to build upon this documentation to harness Cloudly's full capabilities in your infrastructure and process ecosystems. Let the CLI transform your cloud management experience with precision and adaptability.
```bash
# Create a secret
servezone secrets create \
--name database-url \
--value "postgres://user:pass@host/db"
# Create a secret group
servezone secrets create-group \
--name api-secrets \
--secret DATABASE_URL=postgres://... \
--secret REDIS_URL=redis://...
# List secrets
servezone secrets list
# Get secret value
servezone secrets get database-url
# Delete a secret
servezone secrets delete old-secret
```
### 📦 Image Management
```bash
# List images
servezone images list
# Push a new image
servezone images push \
--name myapp \
--version 2.0.0 \
--file ./myapp.tar
# Tag an image
servezone images tag myapp:2.0.0 myapp:latest
# Delete an image
servezone images delete myapp:1.0.0
```
### 📊 Monitoring & Logs
```bash
# View service logs
servezone logs api-service
# Follow logs in real-time
servezone logs api-service --follow
# Filter logs
servezone logs api-service --since 1h --grep ERROR
# Get service status
servezone service status api-service
# Monitor cluster health
servezone clusters health production-cluster
```
### 🔧 DNS Management
```bash
# List DNS records
servezone dns list --domain example.com
# Create a DNS record
servezone dns create \
--domain example.com \
--name api \
--type A \
--value 192.168.1.1
# Update a DNS record
servezone dns update api.example.com --value 192.168.1.2
# Delete a DNS record
servezone dns delete old.example.com
```
## 🎯 Advanced Usage
### Environment Variables
```bash
# Set environment variables for a service
servezone deploy \
--name api-service \
--env NODE_ENV=production \
--env PORT=3000 \
--env DATABASE_URL=@secret:database-url
```
### Configuration Files
Create a `cloudly.yaml` file:
```yaml
cluster: production
service:
name: api-service
image: myapp:latest
replicas: 3
ports:
- 80:3000
environment:
NODE_ENV: production
DATABASE_URL: "@secret:database-url"
```
Deploy using the config file:
```bash
servezone deploy --config cloudly.yaml
```
### Batch Operations
```bash
# Deploy multiple services
servezone deploy --config services/*.yaml
# Update all services in a namespace
servezone service update --namespace api --image-tag v2.0.0
# Delete all staging resources
servezone cleanup --environment staging
```
## 🔄 CI/CD Integration
### GitHub Actions
```yaml
- name: Deploy to Cloudly
run: |
servezone config --url ${{ secrets.CLOUDLY_URL }}
servezone login --token ${{ secrets.CLOUDLY_TOKEN }}
servezone deploy \
--cluster production \
--name api-service \
--image myapp:${{ github.sha }}
```
### GitLab CI
```yaml
deploy:
script:
- servezone config --url $CLOUDLY_URL
- servezone login --token $CLOUDLY_TOKEN
- servezone deploy --config cloudly.yaml
```
## 🎨 Output Formats
```bash
# JSON output for scripting
servezone clusters list --output json
# YAML output
servezone service info api-service --output yaml
# Table output (default)
servezone images list --output table
# Quiet mode (IDs only)
servezone clusters list --quiet
```
## 🛠️ Troubleshooting
```bash
# Enable debug output
servezone --debug clusters list
# Check CLI version
servezone version
# Test connection
servezone ping
# View configuration
servezone config show
# Clear cache and credentials
servezone logout --clear-cache
```
## 📝 Command Reference
```bash
servezone --help # Show all commands
servezone <command> --help # Show command-specific help
servezone clusters --help # Show cluster commands
servezone service --help # Show service commands
servezone secrets --help # Show secret commands
```
## 🔌 Shell Completion
Enable tab completion for your shell:
```bash
# Bash
servezone completion bash > /etc/bash_completion.d/servezone
# Zsh
servezone completion zsh > ~/.zsh/completions/_servezone
# Fish
servezone completion fish > ~/.config/fish/completions/servezone.fish
```
## License and Legal Information
@@ -259,4 +355,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.