Codakey
Play
← Back to ubicloud

How to Deploy & Use ubicloud

Ubicloud Deployment and Usage Guide

1. Prerequisites

System Requirements:

  • Linux-based system (Ubuntu 24.04 recommended for bare metal servers)
  • Docker and Docker Compose
  • Git
  • Ruby runtime (for development)
  • SSH key pair for provider access

Provider Accounts (choose one):

  • Hetzner Robot account with API credentials
  • Leaseweb account
  • AWS Bare Metal account
  • Or any bare metal provider with SSH access

Network Requirements:

  • IPv6 connectivity (or IPv4 tunnel broker like Hurricane Electric's tunnelbroker.net)
  • For Hetzner: Rescue system access to install Ubuntu 24.04

2. Installation

# Clone the repository
git clone git@github.com:ubicloud/ubicloud.git
cd ubicloud

# Generate demo secrets
./demo/generate_env

# Set up Docker containers
docker-compose -f demo/docker-compose.yml up -d

This starts the following services:

  • PostgreSQL database
  • Database migrator
  • Ubicloud application (web interface and respirate service)

3. Configuration

Environment Variables (.env file):

For Hetzner provider (example):

# Hetzner credentials (create via Hetzner Robot web interface)
HETZNER_USER=your_robot_user
HETZNER_PASSWORD=your_robot_password
HETZNER_SSH_PUBLIC_KEY=$(cat ~/.ssh/id_rsa.pub)
HETZNER_SSH_PRIVATE_KEY=$(cat ~/.ssh/id_rsa)

# Optional: IPv4 configuration if your ISP doesn't support IPv6
# Add leased IPv4 addresses from your provider

Bare Metal Server Preparation:

  1. Lease instances from a provider like Hetzner: https://www.hetzner.com/sb
  2. For each instance, use the Hetzner Robot rescue system to install Ubuntu 24.04
  3. Cloudify each server:
# Cloudify a server (run for each bare metal instance)
docker exec -it ubicloud-app ./demo/cloudify_server

When prompted, provide:

  • Hostname/IP of the bare metal server
  • Provider type (hetzner, leaseweb, etc.)

4. Build & Run

Development Mode:

# Access the web console at http://localhost:3000
# The control plane is now running and can manage cloudified servers

# View logs
docker-compose -f demo/docker-compose.yml logs -f

# Stop services
docker-compose -f demo/docker-compose.yml down

Production Considerations:

The control plane uses:

  • Ruby with Roda framework for web interface
  • PostgreSQL for data persistence
  • Committee for OpenAPI validation
  • Cloud Hypervisor as VMM (virtual machine monitor)
  • Linux namespaces for isolation
  • nftables for firewalls and load balancers
  • SPDK for block storage
  • IPsec for encrypted networking

Key Components Architecture:

  • Clover: Main web application (clover.rb)
  • VM Setup: Handles VM provisioning and configuration (vm_setup.rb)
  • Scheduler: Allocates resources across hosts (allocator.rb)
  • Postgres Service: Managed PostgreSQL service (postgres_server_nexus.rb)
  • CSI: Container Storage Interface implementation (csi_pb.rb)

5. Deployment

Managed Service (Easiest): Use the hosted platform at https://console.ubicloud.com

Self-Hosted Options:

  1. Bare Metal Providers:

    • Hetzner (recommended for cost-effectiveness)
    • Leaseweb
    • AWS Bare Metal
    • Any provider with SSH access to Linux servers

  2. Deployment Steps:

# 1. Set up control plane on a management server
git clone git@github.com:ubicloud/ubicloud.git
cd ubicloud
./demo/generate_env
# Edit .env with your provider credentials
docker-compose -f demo/docker-compose.yml up -d

# 2. Provision bare metal servers from your provider
# 3. Cloudify each server using the cloudify_server script
# 4. Access web console to provision cloud resources
  1. Production Deployment Considerations:
    • Use external PostgreSQL for production data
    • Set up proper SSL/TLS termination
    • Configure backup strategies for control plane data
    • Monitor host resources and VM allocations
    • Consider high availability for critical components

Integration Points:

  • GitHub Actions for CI/CD pipelines
  • Kamal for app deployment
  • Custom integrations via REST API (OpenAPI spec available)

6. Troubleshooting

Common Issues:

  1. IPv6 Connectivity Issues:
# If your ISP doesn't support IPv6:
# Option A: Use a VPN (Mullvad recommended)
# Option B: Set up IPv6 tunnel via Hurricane Electric
# Option C: Lease IPv4 addresses from your provider
  1. Cloudify Script Fails:
  • Verify SSH keys are correctly set in .env
  • Check Hetzner Robot credentials have proper permissions
  • Ensure Ubuntu 24.04 is installed via rescue system
  • Verify network connectivity to bare metal server
  1. VM Creation Fails:
  • Check host has sufficient resources (CPU, memory, storage)
  • Verify Cloud Hypervisor is properly installed on host
  • Check nftables rules aren't blocking traffic
  • Review allocation scheduler logs
  1. Storage Issues:
  • Verify SPDK is running on storage hosts
  • Check encryption keys are accessible
  • Ensure sufficient disk space on storage devices
  1. Network Issues:
  • Verify IPsec tunnels are established
  • Check nftables firewall rules
  • Ensure proper routing between VMs
  • Verify DNS resolution (dns_ipv4 setting)

Debug Commands:

# Check container status
docker-compose -f demo/docker-compose.yml ps

# View application logs
docker-compose -f demo/docker-compose.yml logs app

# Check database connectivity
docker exec -it ubicloud-db psql -U postgres

# Verify OpenAPI schema
# The application validates against openapi/openapi.yml

Resource Monitoring:

  • Monitor host utilization via allocator metrics
  • Check VM resource limits (cpu_percent_limit, memory_gib)
  • Review storage volume allocations
  • Monitor network namespace isolation

Getting Help:

← Project overviewView alternatives to ubicloud →