🏙️ Cluster Tools and Your Apps

Two kinds of things run on a LaraKube CLI cluster. From the outside they look the same — a Deployment behind an Ingress — but they arrive differently, live in different namespaces and are redeployed differently. They also share something: the same database, cache and storage services, the Plex Commons.

🧭 The two categories

	Cluster Tools	Your apps
What it is	Ready-made software: an Outline wiki, a Twenty CRM, Matrix chat, Zitadel single sign-on…	Code you write: Laravel, Next.js, Django and the rest
Installed by	That tool's :init, e.g. larakube notes:init	larakube new, nextjs:new or another scaffolder, or larakube init in an existing repo
Where its manifests come from	A template shipped inside the CLI	Your project: .infrastructure/, a Dockerfile, a CI workflow
Has a .larakube.json	No	Yes — that file is what makes a directory a project
Namespace	larakube-shared (single sign-on, VPN, secrets and passwords get their own)	{name}-{environment}, e.g. storefront-production
More than one copy	Another --domain installs another instance	Another environment: local, staging, production
Redeploy	Re-run its :init after upgrading the CLI — there is no CI/CD for tools	larakube cloud:deploy, or your pipeline
Remove	larakube {tool}:remove	larakube down, plus plex:leave or plex:evict for its Commons data
Listed by	larakube tool:list	larakube plex:show

🏘️ One cluster, one Commons

Nobody gets their own copy of PostgreSQL. Each tool and each app environment gets a tenant — its own slice of the shared services:

Service	What a tenant gets
PostgreSQL / MySQL / MariaDB	Its own database and its own login
Valkey (Redis)	Its own logical database — one of 16
S3 storage	Its own bucket (the access keys are shared; isolation is by bucket)
Meilisearch	Its own indexes (the key is shared; isolation is by index name)

🔑 Who allocates what

• A Cluster Tool allocates its own tenant while it installs. notes:init creates Outline's database, Redis slot and bucket, then deploys Outline pointed at them. The tenant is named after the tool and its instance.
• Your app joins with larakube plex:join. new, statamic:new, wordpress:new and nextjs:new run it for you straight after scaffolding; the other frameworks join as each one is verified. The tenant is named after the project and environment: storefront in production, storefront_staging in staging, storefront_local on your machine.

16 Redis slots, shared by both

Cluster Tools and your apps draw from the same 16 logical databases. When they run out, a tool's :init stops with an error, while your app keeps its own Redis pod and still joins for the database and storage. A deleted project's tenant keeps its slot until you reclaim it with larakube plex:evict.

🔍 Which one am I looking at?

• Is there a .larakube.json? Then it's your app.
• Was it installed by a :init command? Then it's a Cluster Tool, and its manifest lives inside the CLI, not in any repo you can push.
• Listing them: tool:list shows Cluster Tools; plex:show shows your apps' Commons tenants. No command shows both — plex:show deliberately hides tool tenants, since a tool isn't anybody's app.

Exceptions worth knowing

• Mail doesn't use the Commons on cloud. Stalwart (mail:init) keeps its own embedded store.
• Some tools can skip the Commons with --no-plex and bundle their own storage: chat, desk, drive, errors, flow, git, insights and sso. The rest need it.
• Your app can opt out too, with --no-plex on the scaffolders that join.
• Monitoring (monitor:init) keeps Grafana's data in a Commons database by default.
• Static sites — Vite, Astro, Docusaurus — have no database, so there's nothing to share.

➡️ Next

• Frameworks — every stack you can scaffold, with its status.
• Share a Commons with Plex — joining, leaving and evicting tenants.
• Shared Tools — the Cluster Tools in depth.