Tutorials

A tutorial is a lesson. It takes you by the hand through a series of steps to build something, so that you learn by doing. It is the right starting point when plexsphere is new to you and you do not yet know enough to ask a precise question.

Tutorials in this section make three promises:

• You will succeed. Every command is exact and every output is shown. If your screen matches the page, you are on track; if it does not, the page tells you so.
• You do not have to decide anything. A tutorial makes the choices for you. Options, trade-offs, and the reasoning behind them belong to the explanation quadrant — not here.
• You will end with a working mental model, not just a running process.

The learning path

Start here — one lesson, and every track below assumes it.

• Set up your local plexsphere — the shortest path from git clone to a running plexsphere on a local kind cluster, with the CLI authenticated against the seeded IdP and ready to explore the /v1 API. It is not part of a track; it is the ground the tracks stand on, so do it once and keep the stack up.

The lessons after it are grouped into four tracks, a capstone, and a teardown. Work through a track in order — each lesson picks up the state the one before it left behind. Where a lesson needs less than that, its entry says so.

Core track — tenancy and identity. Follow these in order; each lesson assumes you finished the one before it. The last is the exception — it needs only the set-up lesson — but it belongs here because it closes the identity arc the track opens.

1. Explore your first Domain — with the stack running, walk the seeded tenant end-to-end through the CLI against the /v1 API and learn how a Domain, its Projects, its identities, and its audit log fit together.
2. Build in your first Domain — now change it: create a Project, invite a user, build a Group and add a member, then read your own writes back out of the per-Domain audit log. Assumes you finished the explore lesson.
3. Grant access through a Group — grant a Group a relation on a Project and watch every member inherit the access, then lose it when they leave the Group. Learn how plexsphere delegates access to roles rather than individuals.
4. Label your first Project — define a Label, grant the two relations that authorize assigning it, attach it to a Project, and see how Labels exist to be selected. Assumes you finished the grant-access lesson.
5. Give a machine its own identity — authenticate a ServiceIdentity with the client_credentials grant, then list, rotate, and revoke its token — the non-interactive counterpart to the plexctl login every lesson so far leaned on. Runnable any time after the set-up lesson: it works in the machine-only svc-demo tenant rather than in Acme Corp.

Provisioning track — a second connected sequence, runnable any time after the set-up lesson. It builds the provisioning catalog against an emulated AWS, binds a credential to a Project, provisions a real cloud Resource, then reaches and watches what you built. Follow these in order; each assumes the one before it.

1. Register a Blueprint — register the official catalog into your Acme Corp Domain as the domain admin and import the aws-s3-bucket Blueprint — the recipe a Resource is provisioned from. A Blueprint needs no Cloud or Credential, so it leads the track, run with the same admin identity the core track uses.
2. Create a Cloud — create the demo AWS Cloud, a provider account plexsphere can provision against — backed locally by the floci emulator, so there is no real account, token, or cost. The platform operator takes over here to build the catalog-global parts.
3. Issue a Cloud Credential — issue the vaulted AWS credential that pays for the Cloud you created — the last piece of the catalog, still run by the platform operator. Builds on Create a Cloud.
4. Assign a Cloud Credential — create a Project and bind the Credential to it under two-party governance: request the assignment by Cloud ID as the project owner, approve it as the platform operator. Builds on the catalog lessons.
5. Provision a cloud Resource — as the project owner, consume the Blueprint and the approved assignment, then resource create an S3 bucket and watch the broker carry it through Pending → Provisioning → Ready against the emulated AWS — a full provisioning lifecycle for a nodeless cloud resource.
6. Reach your Resource — an S3 bucket has nothing to log in to, so this lesson provisions something you can reach: it reuses the demo AWS Cloud and Credential, registers the kubernetes-cloudless-node Blueprint, provisions a Node to Ready, then issues short-lived, mediated sessions (a kubeconfig, a TCP forward, an SSH login) against it — no standing credentials, every issuance audited. Builds on the provisioning track.
7. Watch your Domain — with the Node from Reach your Resource carrying load, read your Domain's capacity snapshot, run a PromQL metrics query and a LogQL logs query through the mediated observability proxy, then store an alert rule: the day-to-day observability surfaces you reach for once the system is running. Run as the Domain admin.

Mesh track — where the tracks above work with tenancy, this sequence works with the mesh: the overlay network of Nodes plexsphere enrols, connects, and re-keys, and the telemetry those Nodes produce. Runnable any time after the set-up lesson; each lesson continues the one before it.

1. Enrol your first Node — mint a single-use bootstrap token, redeem it from a fresh Node to obtain a mesh identity, watch two Nodes form a mesh you can read with plexctl, then rotate a Node's mesh key end to end. You play the part of the Node by hand — the manual counterpart to the broker-driven enrolment in Reach your Resource.
2. Run your first agent — hand the node role to the released plexd agent: one docker run on your own host, then watch it register, heartbeat, and report from the operator's chair. Builds on Enrol your first Node, whose Project and hand-enrolled Nodes are this lesson's starting state.
3. Route logs to your own collector — turn the telemetry story around: start a TLS syslog collector on your own machine, declare it as a sink your Domain owns, grant it to the Project, and route the Project's logs to it until a line you typed shows up inside your container. Builds on Run your first agent, whose agent produces the records this lesson routes.

Platform track — the platform operator's chair. These surfaces are scoped to the platform as a whole rather than to any one Domain, so they gate on the platform manage relation that no Domain admin holds — you sign in with plexctl login --platform to reach them. Runnable any time after the set-up lesson.

1. Read the backup catalog — read what the platform backs up — how, how often, how long it is kept — and the ordered plan for restoring it. The read-only disaster-recovery posture, with no backup run and no restore apply anywhere in sight.

Capstone — take this last, once the tracks above have left a rich audit trail behind. It needs only a running, logged-in stack and the audit entries those lessons recorded.

• Erase an identity from the audit log — honour a GDPR right-to-erasure request against the hash-chained audit log, drop an identity's pseudonym mapping, then prove the chain still verifies end to end and the erasure is itself audited. Pulls together the audit trail you built across the tracks above.

Finish with Tear down your local plexsphere when you want a clean slate — it removes the kind cluster cleanly and carries the reset recipe that rebuilds the stack from a clean baseline when it drifts.

Need more than the lean cluster? When you want every production dependency, the golden-flow end-to-end run, the manifest-to-CI mapping, or the troubleshooting matrix, that material lives in the dev stack runbook in the Contributing handbook — it is a contributor runbook, not a lesson, so it sits outside this learning path.

In a hurry, or want a fully-seeded playground rather than a guided lesson? The runbook's make dev-demo replays the whole provisioning track for you in one command — a couple of Projects, the imported Blueprint, the demo Cloud and Credential, and an S3 Resource running on the local floci emulator — so you can start poking at a working environment immediately. Follow the lessons above when you want to understand how it is built; run make dev-demo when you just want it built.

The demo stack

Lesson 1 brings up a demo stack that seeds a small, fixed world — the same Domains and identities every later lesson works with. You never create these by hand; they are planted for you. It pays to recognise the cast before you start.

Four demo tenant Domains, each isolated from the others:

Slug	Name	What it is for
acme-corp	Acme Corp	Your home tenant — the core track works here throughout.
beta-llc	Beta LLC	A neighbouring tenant, used to show tenancy isolation.
gamma-coop	Gamma Cooperative	A third tenant, so the Domain list has more than two rows.
svc-demo	Service Demo	The machine-identity lesson's tenant; it seeds no human users.

A reserved platform-system Domain also exists for internal platform actors — it is not a tenant you act in.

Three human identities, all fixture accounts on the local IdP, plus one machine account. All three humans sign in with the dev password password:

Identity	Kind	Domains	What it is for
admin@example.com	Human	acme-corp, beta-llc, gamma-coop	Domain admin and auditor; the principal you act as in most lessons, the author who registers the Acme Corp Blueprint catalog in Register a Blueprint (a Domain-scoped catalog is a domain-admin action), and the project owner in Assign a Cloud Credential and Provision a cloud Resource.
operator@example.com	Human	acme-corp (tenant hat) + the Domain-less platform sign-in	The platform operator. Its platform-login identity holds the platform authoring grant, so it signs in with plexctl login --platform to build the catalog-global parts of the provisioning catalog (Create a Cloud, Issue a Cloud Credential) and to approve the credential assignment in Assign a Cloud Credential; its acme-corp row is a plain tenant auditor.
member@example.com	Human	acme-corp	A normal Acme Corp member with no authoring grant; confirms in Register a Blueprint that a Domain-scoped catalog and its blueprints are readable by an ordinary tenant.
svc-deployer	Service identity	svc-demo	The machine account you authenticate in Give a machine its own identity.

When to read this section

• plexsphere is new to you and you want a guided first hour.
• You are onboarding to the repository and want a known-good baseline before you start changing things.

When you instead have a specific job to do — invite an operator, rotate the signing key, register a node — you have outgrown the tutorials. Go to the how-to guides. When you need the exact shape of a surface, go to the reference. When you want to understand why the system is built this way, go to the architecture and bounded-context explanations.