cli/README.md

DeBros CLI

Command-line interface for managing applications on the DeBros decentralized network. This CLI runs on your local development machine, allowing you to build, upload, and deploy applications to the DeBros network from your local environment.

Overview

DeBros CLI allows you to:

• Build and upload applications to the DeBros network
• Deploy applications to your local node
• Configure domains with IPNS for your applications
• Manage .sol domains for easy access to your applications
• Set up K3s with Nginx for container orchestration

Installation

Quick Install Script

The easiest way to install the DeBros CLI on your local machine is using our install script:

curl -sL https://raw.githubusercontent.com/DeBrosOfficial/node/main/packages/@debros/cli/install-cli.sh | bash

This script will:

1. Check for Node.js, Docker, and IPFS dependencies
2. Install IPFS if needed (with your permission)
3. Install the DeBros CLI globally
4. Set up the necessary configuration directories

Manual Installation

Alternatively, you can install manually:

# Global installation with npm
npm install -g @debros/cli

# Or with pnpm
pnpm install -g @debros/cli

# Or with yarn
yarn global add @debros/cli

Prerequisites

• Node.js 18+
• Docker
• IPFS (for some commands)
• K3s (optional, for container orchestration)

Getting Started

Initialize the CLI and environment:

debros init

This will guide you through setting up your environment, including K3s and Nginx if desired.

Commands

Upload an Application (and Update)

debros upload <folder> [options]

Options:

• -t, --tag <tag>: Docker image tag (default: "latest")
• -n, --name <name>: Application name (defaults to folder name)
• -d, --domain <subdomain>: Custom subdomain (only specify the part before .debros.sol)

Example:

# Using default subdomain (awesome-app.debros.sol)
debros upload ./my-app -n awesome-app -t v1.0.0

# Using custom subdomain (api-myproject.debros.sol)
debros upload ./my-app -n awesome-app -d api-myproject

# Update an existing application
# (uploading with the same name will update the existing deployment)
debros upload ./my-app -n awesome-app -t v1.1.0

The upload command is used both for initial deployment and for updates. When you upload a new version of an existing application, the network automatically updates the deployment.

Deploy Locally

debros deploy <image-path> [options]

Options:

• -n, --name <name>: Application name (if not provided, derived from image name)

Note: All applications run on port 8787 internally and are automatically deployed with 2 replicas for redundancy in the 'debros-apps' namespace. External access is standardized through port 80 via Nginx using K3s.

Example:

debros deploy awesome-app.tar -n awesome-app

List Deployments and Network

debros list [options]

Options:

• -a, --apps: List deployed applications
• -n, --nodes: List network nodes
• -i, --images: List local Docker images
• -d, --detailed: Show detailed information

List Application Versions

debros versions <app-name>

Example:

debros versions awesome-app

This will show all available versions of the application along with their upload timestamps and deployment status.

Rollback Application

debros rollback <app-name> [version-tag]

Options:

• -f, --force: Force rollback without confirmation

Example:

# Rollback to a specific version
debros rollback awesome-app v1.0.0

# Rollback to the previous version
debros rollback awesome-app

Stop Application

debros stop <app-name>

Options:

• -f, --force: Force stop without confirmation

Example:

debros stop awesome-app

Start Application

debros start <app-name>

Options:

• -v, --version <version>: Version tag to start (defaults to latest)

Example:

# Start with latest version
debros start awesome-app

# Start with specific version
debros start awesome-app -v v1.0.0

Delete Application

debros delete <app-name>

Options:

• -f, --force: Force delete without confirmation

Example:

debros delete awesome-app

Configure IPNS

debros configure-ipns <name> <cid>

Example:

debros configure-ipns awesome-app QmXYZ123...

Domain Management

Check domain availability:

debros domain check <domain>

Register a domain:

debros domain register <domain>

Link a domain to IPNS:

debros domain link <domain> <ipns-address>

Set up a domain with application and IPNS in one step:

debros domain setup <domain> <cid>

Docker Deployment vs K3s

The CLI supports two deployment strategies:

1. Docker: Simple container deployment on a single node
2. K3s: Kubernetes-based orchestration with Nginx for routing

K3s is recommended for production deployments as it provides better scaling, failover, and routing capabilities.

Example Workflow

Here's a typical workflow for deploying an application to the DeBros network:

# 1. Initialize the CLI on your local machine
debros init

# 2. Upload your application to the network
# IMPORTANT: Your application should listen on port 8787 internally
debros upload ./my-app
# Or with a custom subdomain
debros upload ./my-app -d api-myservice

# This will:
# - Build a Docker image from your application folder
# - Save the image to a tar file
# - Upload the tar file to IPFS, getting a CID
# - Announce the deployment to the network
# - DeBros nodes will automatically pull and deploy your application with 2 replicas
# - Your application gets the subdomain: my-app.debros.sol (or api-myservice.debros.sol)
# - External traffic is managed via Nginx routing based on domain name

# 3. List your deployments and network nodes
debros list

# 4. Update your application (when you make changes)
debros upload ./my-app -t v1.1.0

# 5. View version history and manage versions
debros versions my-app

# 6. Rollback to a previous version if needed
debros rollback my-app v1.0.0

# 7. Stop, start, and delete applications
debros stop my-app
debros start my-app
debros delete my-app
debros domain setup my-app.debros.sol QmXYZ123...

# 5. Check if your application is deployed on the network
debros list -a

Deployment Process Overview

When you use the DeBros CLI to deploy an application to the network:

1. Your application is dockerized and should listen on port 8787
2. The CLI builds, uploads and announces the app to the network
3. You specify a subdomain (e.g., "anchat-api") that will be used to access your app
4. The CLI automatically appends ".debros.sol" to your subdomain
5. DeBros nodes automatically pull and deploy your application with K3s and Nginx
6. Your app becomes accessible at the specified domain (e.g., anchat-api.debros.sol)
7. All routing between domains and apps is handled transparently by the network

Standardized Application Configuration

For consistency and reliability across the DeBros network, all applications follow these standardized rules:

Port Standardization:

• All applications MUST listen on port 8787 internally
• External traffic is routed through port 80 via Nginx
• Domain-based routing (app-name.debros.sol) handles multiple applications on the same nodes
• Port configuration is handled automatically by the CLI and node infrastructure

Replica Management:

• All applications are automatically deployed with 2 replicas for redundancy
• Replicas are distributed across different nodes when possible
• If a node fails, traffic is automatically routed to healthy replicas
• Scaling is handled transparently by the network

Environment Variables:

• The following environment variables are automatically set:
  • PORT=8787: Tells your application which port to listen on
  • DEBROS_APP_NAME: Your application's name on the network

Remote vs Local Operations

The DeBros CLI distinguishes between operations on your local machine and operations that interact with the DeBros network:

Local Operations:

• Building Docker images
• Uploading files to IPFS
• Managing local K3s deployments

Network Operations:

• Discovering network nodes
• Announcing deployments to the network
• Managing node lists and application distribution
• Setting up domains and IPNS

IPFS and IPNS

The CLI integrates with IPFS and IPNS to provide decentralized content addressing and name resolution. This allows you to:

• Store application images and data on IPFS
• Use IPNS for stable naming despite content changes
• Link .sol domains to your IPNS addresses

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

GNU GPL v3.0