photoncloud-monorepo/README.md

PhotonCloud

PhotonCloud is a Nix-first cloud platform workspace that assembles a small control plane, network services, VM hosting, shared storage, object storage, and gateway services into one reproducible repository.

The canonical local proof path is the six-node VM cluster under nix/test-cluster. It builds all guest images on the host, boots them as hardware-like QEMU nodes, and validates real multi-node behavior.

Components

• chainfire: replicated coordination store
• flaredb: replicated KV and metadata store
• iam: identity, token issuance, and authorization
• prismnet: tenant networking control plane
• flashdns: authoritative DNS service
• fiberlb: load balancer control plane and dataplane
• plasmavmc: VM control plane and worker agents
• coronafs: shared filesystem for mutable VM volumes
• lightningstor: object storage and VM image backing
• k8shost: Kubernetes-style hosting control plane
• apigateway: external API and proxy surface
• nightlight: metrics ingestion and query service
• creditservice: minimal reference quota/credit service
• deployer: bootstrap and phone-home deployment service
• fleet-scheduler: non-Kubernetes service scheduler for bare-metal cluster services

Quick Start

nix develop
nix run ./nix/test-cluster#cluster -- fresh-smoke

Main Entrypoints

• workspace flake: flake.nix
• VM validation harness: nix/test-cluster/README.md
• shared volume notes: coronafs/README.md
• minimal quota-service rationale: creditservice/README.md
• archived manual VM launch scripts: baremetal/vm-cluster/README.md

Repository Guide

• docs/README.md: documentation entrypoint
• docs/testing.md: validation path summary
• docs/component-matrix.md: supported multi-component compositions
• docs/storage-benchmarks.md: latest CoronaFS and LightningStor lab numbers
• plans/: design notes and exploration documents

Scope

PhotonCloud is centered on reproducible infrastructure behavior rather than polished end-user product surfaces. Some services, such as creditservice, are intentionally minimal reference implementations that prove integration points rather than full products.

Host-level NixOS rollout validation is also expected to stay reproducible: the deployer-vm-smoke VM test now proves that nix-agent can activate a prebuilt target system closure directly, without recompiling the stack inside the guest.