Overview and prerequisites

This section is for the person installing the platform. If you are a user of an installation someone else runs, start at Your first server.

What you are building

your laptop / CI ──► control plane (containers + PostgreSQL)
                            ▲
                            │ outbound HTTPS, opened by the region
                     ┌──────┴──────────────────────────────┐
                     │ region: agent VM                    │
                     │   ├─ Proxmox VE cluster             │
                     │   ├─ storage (ZFS or Ceph)          │
                     │   └─ edge router (public block)     │
                     └─────────────────────────────────────┘

Two independent deployables: the control plane (anywhere that can run containers and PostgreSQL) and one agent virtual machine per region (inside the region). They are updated separately and neither blocks the other.

Prerequisites

Settle all of these before creating anything. Two of them are very expensive to change later.

#	Requirement	Notes
1	A Proxmox VE cluster	Any node count. Three or more if you want quorum
2	Shared or replicated storage	Ceph, or ZFS with replication. zone9 places disks; it does not manage the backend
3	A routed public IPv4 block	Routed, not bridged. Confirm with your upstream that the whole block is routed to your edge’s WAN address — this is easy to assume wrongly and painful to discover late
4	An edge router you can program	FortiGate today. Others need an adapter
5	A tenant address plan	Must not overlap anything in your datacentre. Write it down before creating anything — renumbering an EVPN fabric later is not a small job
6	Somewhere to run the control plane	Kubernetes is what production uses; a container host works
7	A PostgreSQL database	Managed or self-run
8	A DNS provider account	Cloudflare, if you want managed DNS and TLS
9	Outbound HTTPS from the region	The only network requirement. No inbound rule

Items 3 and 5 are the ones to get right up front.

Order of installation

1. Prepare Proxmox — roles, tokens, pools. Nothing else works without the right privileges
2. Network and edge — SDN fabric, the public block, the edge policy
3. Deploy the control plane — containers, database, schema
4. Region agent — the VM that runs jobs in your region
5. Region configuration — the file that describes your region to the agent
6. Machine images — templates users create servers from
7. First tenant — an organisation, a pool, a server

Steps 1 and 2 are operator work with your own credentials. From step 3 onwards you are configuring zone9.

What stays your responsibility

zone9 does not manage your infrastructure, and this is a design boundary rather than a gap:

• Hypervisor node configuration and patching
• Physical switches, VLAN trunks, cabling
• The storage backend and its encryption
• The edge router’s own policy and routing
• Backup — use Proxmox Backup Server
• The control plane’s own availability

A control plane that also reconfigures switches and hypervisor nodes is one whose bug takes the datacentre with it. See What zone9 is.

Conventions in this section

Placeholders are written as <angle brackets>. Substitute your own values; nothing here contains a real address from any installation.