Quickstart

Get Uncloud up and running on your machine. This guide walks you through starting the backend API server and the frontend dashboard.

Prerequisites

Go 1.21+ — Install Go
Node.js 18+ — Install Node.js
Kubernetes cluster — K3s recommended for development
kubectl — Configured to talk to your cluster

1. Clone the Repository

git clone https://github.com/dukaancloud/dukaancloud.git
cd dukaancloud

2. Start the Backend

cd backend
go mod download
go run cmd/api/main.go

The API server starts on http://localhost:8080 by default.

On first run, the SQLite database is automatically created at data/nebula.db with all required tables.

Environment Variables

Variable	Default	Description
`HTTP_PORT`	`8080`	API server port
`DB_PATH`	`data/nebula.db`	SQLite database path
`KUBECONFIG`	Auto-detected	Path to Kubernetes config
`PROMETHEUS_URL`	`http://localhost:30090`	Prometheus endpoint

3. Start the Frontend

cd frontend
npm install
npm run dev

The dashboard opens at http://localhost:5173.

Set VITE_API_URL=http://localhost:8080 in a .env file to point the frontend at the backend API.

4. Run the Admin Setup

On first launch, navigate to Admin → Setup in the dashboard. The provisioner system will guide you through installing infrastructure components:

K3s — Lightweight Kubernetes distribution
KubeVirt — Virtual machine management
Storage Class — Persistent volume provisioner
Metrics Server — Resource usage metrics
CoreDNS — DNS resolution
Container Registry — Image storage
CloudNativePG — PostgreSQL operator
Object Storage — S3-compatible storage

Click Run All to install everything at once, or run individual steps.

5. Create Your First Resources

Create a Project

curl -X POST http://localhost:8080/api/v1/projects \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project"}'

Launch a Droplet (VM)

curl -X POST http://localhost:8080/api/v1/droplets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-vm",
    "image": "ubuntu-22-04",
    "plan_id": "s-1vcpu-1gb",
    "region": "nyc1",
    "ssh_key_ids": []
  }'

Deploy an App

curl -X POST http://localhost:8080/api/v1/apps \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello-world",
    "source_type": "image",
    "image_url": "nginx:latest",
    "port": 80
  }'

What’s Next?

Deploy a VM

Detailed guide on creating and managing Droplets

Deploy an App

Build and deploy applications on the App Platform

API Reference

Explore the full REST API

Architecture

Understand how everything fits together

Getting Started

Core Concepts

Prerequisites

1. Clone the Repository

2. Start the Backend

Environment Variables

3. Start the Frontend

4. Run the Admin Setup

5. Create Your First Resources

Create a Project

Launch a Droplet (VM)

Deploy an App

What’s Next?

Deploy a VM

Deploy an App

API Reference

Architecture

​Prerequisites

​1. Clone the Repository

​2. Start the Backend

​Environment Variables

​3. Start the Frontend

​4. Run the Admin Setup

​5. Create Your First Resources

​Create a Project

​Launch a Droplet (VM)

​Deploy an App

​What’s Next?

Deploy a VM

Deploy an App

API Reference

Architecture

Prerequisites

1. Clone the Repository

2. Start the Backend

Environment Variables

3. Start the Frontend

4. Run the Admin Setup

5. Create Your First Resources

Create a Project

Launch a Droplet (VM)

Deploy an App

What’s Next?