Skip to content

user-guide.md

Latest commit

 

History

History
340 lines (232 loc) · 7.3 KB

user-guide.md

File metadata and controls

340 lines (232 loc) · 7.3 KB

BitBuilder Cloud CLI User Guide

Introduction

BitBuilder Cloud CLI (bbctl) is a command-line tool for provisioning and managing infrastructure across multiple providers, focusing on bare metal deployments with VyOS and Proxmox. It's designed to offer a seamless experience similar to fly.io's flyctl, but targeted at self-hosted infrastructure.

This guide will help you understand how to use bbctl effectively, covering installation, basic operations, and advanced features.

Getting Started

Installation

Using Cargo (Recommended)

If you have Rust installed, the simplest way to install bbctl is via Cargo:

cargo install bbctl

From Binary Releases

For systems without Rust, download pre-compiled binaries:

  1. Visit the releases page
  2. Download the appropriate binary for your platform
  3. Make it executable: chmod +x bbctl
  4. Move it to your PATH: sudo mv bbctl /usr/local/bin/

Building from Source

To build the latest version from source:

git clone https://github.com/bitbuilder-io/bbctl.git
cd bbctl
cargo build --release

The compiled binary will be in target/release/bbctl.

First-Time Setup

When running bbctl for the first time, you'll need to set up your provider credentials:

# Initialize bbctl configuration
bbctl init

# Add a VyOS provider
bbctl providers add vyos-router --type vyos --host 192.168.1.1 --username vyos --api-key your-api-key

# Add a Proxmox provider
bbctl providers add proxmox-host --type proxmox --host 192.168.1.2 --token-id your-token-id --token-secret your-token-secret

Core Concepts

BitBuilder Cloud CLI organizes resources into the following categories:

  • Providers: Infrastructure providers like VyOS routers or Proxmox hosts
  • Regions: Logical groupings of infrastructure, typically by location
  • Instances: Virtual machines running on the providers
  • Volumes: Storage volumes that can be attached to instances
  • Networks: Virtual networks for connecting instances

Working with Providers

Listing Providers

bbctl providers list

Testing Provider Connectivity

bbctl providers test vyos-router

Removing a Provider

bbctl providers remove vyos-router

Managing Instances

Creating an Instance

bbctl instances create web-server-1 \
  --provider vyos-router \
  --region nyc \
  --cpu 2 \
  --memory 4 \
  --disk 80

Listing Instances

bbctl instances list

Starting and Stopping Instances

# Start an instance
bbctl instances start i-01234567

# Stop an instance
bbctl instances stop i-01234567

Getting Instance Details

bbctl instances show i-01234567

Deleting an Instance

bbctl instances delete i-01234567

Working with Volumes

Creating a Volume

bbctl volumes create db-data \
  --size 100 \
  --region nyc

Listing Volumes

bbctl volumes list

Attaching a Volume to an Instance

bbctl volumes attach vol-01234567 \
  --instance i-01234567

Detaching a Volume

bbctl volumes detach vol-01234567

Managing Networks

Creating a Network

bbctl networks create app-network \
  --cidr 192.168.1.0/24

Listing Networks

bbctl networks list

Connecting an Instance to a Network

bbctl networks connect net-01234567 \
  --instance i-01234567

Disconnecting an Instance

bbctl networks disconnect net-01234567 \
  --instance i-01234567

Using the Terminal UI (TUI)

BitBuilder Cloud CLI includes an interactive terminal interface that can be launched by running bbctl without any commands.

Navigating the TUI

  • Use Tab or number keys (1-5) to switch between views
  • Use arrow keys or j/k to select items in lists
  • Press Enter to view or interact with a selected item
  • Press ? to view help

TUI Views

  1. Home: Dashboard with summary information
  2. Instances: List and manage virtual machines
  3. Volumes: Manage storage volumes
  4. Networks: Configure virtual networks
  5. Settings: Configure bbctl options

TUI Key Bindings

Key Action
1-5 Switch to numbered view
Tab Next view
Shift+Tab Previous view
j or ↓ Move selection down
k or ↑ Move selection up
Enter View or interact with item
a Add new item
d Delete selected item
e Edit selected item
r Refresh data
q or Esc Quit or go back
? Show help

Configuration Files

BitBuilder Cloud CLI uses the following configuration files in ~/.bbctl/:

  • settings.toml: Global settings for bbctl
  • providers.toml: Provider configurations
  • credentials.toml: Authentication credentials (API keys, tokens, etc.)

Example Settings File

default_provider = "vyos-router"
default_region = "nyc"
telemetry_enabled = false
auto_update_enabled = true
colors_enabled = true
default_cpu = 2
default_memory_gb = 4
default_disk_gb = 80
log_level = "info"

Advanced Usage

Using Environment Variables

You can use environment variables to override configuration values:

export BBCTL_DEFAULT_PROVIDER=vyos-router
export BBCTL_LOG_LEVEL=debug

Scripting and Automation

For scripting, you can use the --json flag with most commands to get machine-readable output:

bbctl instances list --json > instances.json

WireGuard Secure Networking

BitBuilder Cloud CLI supports setting up WireGuard for secure connectivity:

bbctl networks create secure-net \
  --cidr 10.10.0.0/24 \
  --wireguard enabled

Troubleshooting

Common Issues

Connection Problems

If you're having trouble connecting to a provider:

# Test provider connectivity with verbose output
bbctl providers test vyos-router --verbose

# Ensure credentials are correct
bbctl providers update vyos-router --api-key new-api-key

Command Failures

For detailed error information, increase the log level:

bbctl --log-level debug instances list

Configuration Issues

If you suspect configuration problems:

# View current configuration
bbctl config show

# Reset configuration
bbctl config reset

Getting Help

For additional help with specific commands:

bbctl help
bbctl instances --help

Conclusion

BitBuilder Cloud CLI provides a powerful, unified interface for managing multi-tenant infrastructure across VyOS and Proxmox providers. By combining the command-line interface with the interactive TUI, you can efficiently manage your infrastructure whether you're working interactively or scripting automated workflows.

For more detailed information, refer to the other documentation:

Additional Resources