NullCloud - backend

A fake cloud provider API — provision VPCs, subnets, and virtual server instances without any real infrastructure. Useful for demos, tests, and Terraform provider development.

Using Terraform? The terraform-provider-nullcloud wraps this API and lets you manage NullCloud resources with .tf files.

Install

brew tap we-work-in-the-cloud/backend-nullcloud https://github.com/we-work-in-the-cloud/backend-nullcloud
brew install --cask nullcloud-backend

Resources

• VPC
• Subnet
• Virtual Server Instance (VSI)
• Load Balancer
• Object Storage Bucket
• Managed Database
• Kubernetes Cluster

Model Classes

classDiagram

    namespace Network {
        class VPC {
            string id
            string name
            string status
            string crn
            string region
            time.Time created_at
        }

        class Subnet {
            string id
            string name
            string status
            string crn
            string vpc_id
            string zone
            string cidr_block
            time.Time created_at
        }

        class LoadBalancer {
            string id
            string name
            string status
            string crn
            string protocol
            int port
            LoadBalancerTarget[] targets
            time.Time created_at
        }

        class LoadBalancerTarget {
            string type
            string id
        }
    }

    namespace Compute {
        class VSI {
            string id
            string name
            string status
            string crn
            string subnet_id
            string profile
            string image
            string primary_ip
            time.Time created_at
        }
        class KubernetesCluster {
            string id
            string name
            string status
            string crn
            string version
            int node_count
            string[] subnet_ids
            time.Time created_at
        }
    }

    namespace Data {
        class Bucket {
            string id
            string name
            string status
            string crn
            string region
            time.Time created_at
        }

        class Database {
            string id
            string name
            string status
            string crn
            string engine
            string version
            string plan
            string[] subnet_ids
            time.Time created_at
        }
    }

    VPC "1" -- "*" Subnet : contains
    LoadBalancerTarget --> VSI : points to vsi
    Subnet "1" -- "*" VSI : hosts
    LoadBalancerTarget --> KubernetesCluster : points to cluster
    Subnet "1" -- "*" Database : uses
    LoadBalancer "1" -- "*" LoadBalancerTarget : targets
    Subnet "1" -- "*" KubernetesCluster : uses

Loading

Auth

All requests require an Authorization header. Any non-empty string works. Resources are scoped to the token — different tokens are isolated from each other.

Persistence

Mode	Flag	Notes
In-memory	(default)	State lost on restart
JSON file	--store-file <path>	State persisted to disk

Run

# In-memory (default)
./nullcloud-backend

# With file persistence
./nullcloud-backend --store-file store.json

# Custom port (default: 8080)
./nullcloud-backend --port 9090

Docker

Build the minimal distroless image from the repository root:

docker build -t nullcloud-backend:local .

Run the API and UI on port 8080 with JSON state persisted on a mounted host directory:

mkdir -p ./nullcloud-data
# The distroless image runs as UID/GID 65532 (nonroot).
sudo chown 65532:65532 ./nullcloud-data
docker run --rm -p 8080:8080 \
  -v "$(pwd)/nullcloud-data:/data" \
  nullcloud-backend:local

The image exposes port 8080, listens on all container interfaces, and defaults to /data/store.json for persistence. Docker-managed volumes at /data are writable by the non-root user. Bind-mounted host directories must be writable by UID/GID 65532. The API is available under /v1 and the UI under /ui. Override the default flags by supplying arguments after the image name (for example, --port 9090).

Build

make build     # builds for current platform → ./nullcloud-backend

Test

make test