photoncloud-monorepo/docs/README.md

Docs

This directory is the public documentation entrypoint for UltraCloud.

Read First

• ../README.md
• testing.md
• component-matrix.md
• rollout-bundle.md
• control-plane-ops.md
• edge-trial-surface.md
• provider-vm-reality.md
• hardware-bringup.md
• storage-benchmarks.md

Canonical Profiles

• single-node dev: nix run .#single-node-quickstart, nix run .#single-node-trial, nix build .#single-node-trial-vm, nixosConfigurations.single-node-quickstart, companion image nixosConfigurations.netboot-all-in-one
• 3-node HA control plane: nixosConfigurations.node01, nixosConfigurations.node02, nixosConfigurations.node03, companion image nixosConfigurations.netboot-control-plane
• bare-metal bootstrap: nix run ./nix/test-cluster#cluster -- baremetal-iso, nixosConfigurations.ultracloud-iso, nixosConfigurations.baremetal-qemu-control-plane, nixosConfigurations.baremetal-qemu-worker, checks.x86_64-linux.baremetal-iso-e2e followed by ./result/bin/baremetal-iso-e2e for the exact host-KVM proof

nixosConfigurations.netboot-worker is an archived helper outside the canonical profiles and their guard set. baremetal/vm-cluster, k8shost-cni, k8shost-controllers, lightningstor-csi, Firecracker, and mvisor remain in-tree only as non-product scaffolds or legacy/manual debugging paths.

single-node-trial-vm is the low-friction trial artifact for local use. OCI/Docker artifact is intentionally not the public trial surface because a privileged container would not exercise the same KVM, /dev/net/tun, and guest-kernel contract.

ultracloud.cluster backed by nix/lib/cluster-schema.nix is the only supported cluster authoring source. nix-nos is limited to legacy compatibility and low-level network primitives. single-node-trial-vm and single-node-quickstart are the standalone VM-platform story.

Key References

• VM validation harness: ../nix/test-cluster/README.md
• Hardware bring-up bridge: hardware-bringup.md
• Provider and VM-hosting reality proof: provider-vm-reality.md
• Rollout bundle operator contract: rollout-bundle.md
• Core control-plane operator contract: control-plane-ops.md
• Edge and trial-surface contract: edge-trial-surface.md
• APIGateway supported scope: ../apigateway/README.md
• NightLight supported scope: ../nightlight/README.md
• CoronaFS storage role: ../coronafs/README.md
• CreditService supported scope: ../creditservice/README.md
• K8sHost supported scope: ../k8shost/README.md

Core API Notes

• chainfire supports fixed-membership cluster introspection on the public surface: MemberList, Status, and the internal Vote plus AppendEntries Raft transport. chainfire-core remains a workspace-internal compatibility crate rather than a supported embeddable API.
• flaredb supports SQL over both gRPC and REST. The public REST endpoints are POST /api/v1/sql and GET /api/v1/tables.
• lightningstor keeps bucket versioning, bucket policy, bucket tagging, and explicit object version listing on the supported optional surface.
• k8shost keeps WatchPods on the supported surface as a bounded snapshot stream of the current matching pods.

Design Notes

Longer-running redesign and investigation documents remain in plans/. Those documents are useful context, but they are not the primary onboarding path for contributors.