Quickstart

​
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

VariableDefaultDescription
HTTP_PORT8080API server port
DB_PATHdata/nebula.dbSQLite database path
KUBECONFIGAuto-detectedPath to Kubernetes config
PROMETHEUS_URLhttp://localhost:30090Prometheus 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:
  1. K3s — Lightweight Kubernetes distribution
  2. KubeVirt — Virtual machine management
  3. Storage Class — Persistent volume provisioner
  4. Metrics Server — Resource usage metrics
  5. CoreDNS — DNS resolution
  6. Container Registry — Image storage
  7. CloudNativePG — PostgreSQL operator
  8. 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