docs(development): explain why packages live in apps vs extra#594
Conversation
Ground the apps/extra split in Cozystack's managed-services model: apps are first-class services a user orders directly; extra are enabler modules switched on per-tenant that power those services under the hood. Add concrete examples (S3 bucket over SeaweedFS, Managed Kubernetes over etcd) and a decision guide covering single, private dependencies bundled inside a chart. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Andrei Kvapil <kvapss@gmail.com>
✅ Deploy Preview for cozystack ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe v1.5 development documentation defines four Cozystack package categories, clarifies ChangesPackage type documentation expansion
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Warning Tools execution failed with the following error: Failed to run tools: 13 INTERNAL: Received RST_STREAM with code 2 (Internal server error) Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the development documentation to clarify the architecture of Cozystack packages, introducing detailed explanations of the four package categories (core, system, apps, and extra) and a decision guide for choosing between them. The review feedback suggests minor improvements to the text, including refining the AWS/GCP comparison to focus on managed offerings, correcting a grammatical agreement issue, and adding commas after 'e.g.' for consistency.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
…rences vm-disk) Clarify that dependencies also exist between first-class services: when a dependency has its own lifecycle and value, it stays an apps service and other apps reference it (vm-instance attaches an existing vm-disk by name) rather than bundling or moving it to extra. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Andrei Kvapil <kvapss@gmail.com>
Andrei Kvapil (kvaps)
requested a review
from Timofei Larkin (lllamnyp)
as a code owner
… commas) Refine the AWS/GCP analogy to reference their managed offerings, fix subject-verb agreement for extra modules, and add the comma after e.g. for consistency with the rest of the document. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Andrei Kvapil <kvapss@gmail.com>
IvanHunters
left a comment
IvanHunters
left a comment
There was a problem hiding this comment.
Accurate and well-written — I cross-checked every claim (package inventory, chart descriptions, the bucket->seaweedfs BucketClass wiring, etcd->kubernetes, the bundled alerta-db PostgreSQL, the former ferretdb bundling) against the monorepo and they hold.
One nit: extra/seaweedfs is quoted as "Managed SeaweedFS Service", but the actual Chart.yaml description is just Seaweedfs. Since the surrounding descriptions are verbatim chart strings, either use the real string or drop the quotes and phrase it as a gloss.
Optional: a one-line pointer on how apps/extra placement affects bundle/variant selection and PackageSource wiring would help a contributor go from "where does my package go" to "how do I make it ship".
myasnikovdaniil
left a comment
myasnikovdaniil
left a comment
There was a problem hiding this comment.
Nice improvement — the old text described apps vs extra purely mechanically ("shown in the catalog" vs "not shown"), which never told a contributor where a new package belongs. The managed-services framing and the "Choosing apps, extra, or a bundled dependency" decision guide are exactly what was missing, and the vm-disk/vm-instance "reference, don't bundle" example is a genuinely good one.
A few precision points on the examples, so the page doesn't go stale or over-promise on the neatness of the split (all inline). None of them are blockers — happy to /lgtm once the etcd note below is addressed one way or another.
| So a tenant administrator *enables the SeaweedFS module once*, and from then on users | ||
| can order S3 buckets as a first-class service. The user consumes a bucket; they never | ||
| see, order, or manage SeaweedFS itself — it is an implementation detail of "S3 bucket". | ||
| The same relationship holds for `extra/etcd` ("Storage for Kubernetes clusters"), which |
There was a problem hiding this comment.
Heads-up: etcd is the flagship extra example here, but there's an active design proposal to remove exactly this arrangement — community#25 proposes retiring the etcd tenant module and folding etcd into the kubernetes app (one etcd per cluster, no tenant-level sharing). If #25 lands, this paragraph is the first thing that goes stale.
Suggestion: either add a short forward-note ("etcd's placement as a tenant module is under review — see community#25"), or lead the section with a more stable flagship example (seaweedfs → bucket is already the cleaner illustration and isn't being reworked). Not blocking the PR, just avoiding a same-week staleness.
There was a problem hiding this comment.
Good point — I dropped the etcd example entirely, so the section stays valid regardless of how community#25 lands. seaweedfs → bucket remains the flagship example.
| The same relationship holds for `extra/etcd` ("Storage for Kubernetes clusters"), which | ||
| provides the datastore for `apps/kubernetes` managed clusters. Other `extra` modules | ||
| supply tenant-wide infrastructure rather than orderable services: `extra/ingress` | ||
| (NGINX Ingress Controller), `extra/gateway` (per-tenant Gateway API backed by Cilium), |
There was a problem hiding this comment.
This example list is slightly off against the code:
extra/external-dnsisn't a per-tenant toggle — it's not in theTenantchart's schema (packages/apps/tenant/values.yamlonly hasetcd/monitoring/ingress/gateway/seaweedfs), and its release definition iscategory: Networkingwith nointernal.cozystack.io/tenantmodulelabel. So it doesn't fit the "an enabler a tenant switches on" definition this section just gave — it behaves like a normal app that happens to live inextra/.extra/gatewayhas no-rd/ApplicationDefinition at all, so it has no dashboard/catalog presence — it's toggle-only (and auto-enabled for derived-apex tenants). Fine to mention, but it's not shown anywhere the wayingress/monitoringare.
Suggestion: keep ingress + monitoring as the tenant-module examples (they cleanly match the definition) and either drop external-dns or call it out as the "lives in extra but is really just an app" case.
There was a problem hiding this comment.
You're right on both counts. Dropped external-dns from the list — it matches neither category as written, so I filed cozystack/cozystack#3275 to settle its placement (proper enabler module if it's a per-tenant singleton, move to apps if multi-instance makes sense). Kept ingress + monitoring as the examples and marked gateway as toggle-only.
| `extra` packages are **enabler modules**, not first-class services. A user never orders | ||
| them as a final entity; instead they are switched on as **tenant options**, and once | ||
| enabled they provide capabilities that the `apps` services build on — working under the | ||
| hood. For that reason they are *not* shown in the application catalog and can only be |
There was a problem hiding this comment.
Minor: "not shown in the application catalog" is correct (the console excludes module/Administration definitions from the Marketplace — apps/console/src/routes/MarketplaceList.tsx), but they're not invisible — they appear under Administration → Modules (routes/ModulesPage.tsx) and are configured there per tenant. Consider "not shown in the application catalog (they appear under Administration → Modules instead)" so a reader doesn't expect them to be entirely absent from the dashboard. Optional nit.
There was a problem hiding this comment.
Done, added the pointer.
- Drop the etcd example so the section stays valid regardless of the outcome of the per-cluster etcd proposal - Drop external-dns from the extra examples: it behaves like a regular app and its placement is tracked in a separate issue - Note that extra modules appear under Administration -> Modules - Remove the non-verbatim seaweedfs chart description quote Assisted-By: Claude Signed-off-by: Andrei Kvapil <kvapss@gmail.com>
myasnikovdaniil
left a comment
myasnikovdaniil
left a comment
There was a problem hiding this comment.
LGTM — all three points from the earlier pass are addressed and verified against the code.
- etcd example dropped — seaweedfs → bucket is now the flagship, so the section no longer rides on the community#25 outcome.
- external-dns removed from the
extralist (placement tracked in cozystack/cozystack#3275);ingress+monitoringkept as the tenant-module examples;gatewaycorrectly marked toggle-only — no ApplicationDefinition, Cilium-backed, auto-enabled for derived-apex tenants (matchespackages/apps/tenant/values.yaml). - Administration → Modules pointer added.
New claims check out too: app display names match each chart's description:, extra/seaweedfs BucketClass ↔ apps/bucket BucketClaim, monitoring's bundled Alerta Postgres, and the former ferretdb's bundled Postgres.
Two non-blocking notes:
apps/vm-diskis quoted as "Virtual Machine Disk", but the chart description is "Virtual Machine disk" (lowercase d) — trivial.- The Netlify preview is red, but the deploy-preview build (
npm install && ./hack/download_openapi.sh && hugo --gc --minify --buildFuture) reproduces green locally on the pinned hugo 0.160.1 — the failure looks environmental, not content-related; a retrigger should clear it.
3 participants
What
Expands the Packages section of the v1.5 Developer Guide to explain why some applications live in
packages/appsand others inpackages/extra, grounding the split in Cozystack's managed-services model.Why
The previous text described the two categories only mechanically ("shown in the dashboard catalog" vs "not shown, installed as part of a tenant"), which doesn't tell a contributor where a new component belongs. This adds the underlying principle and a concrete decision guide.
Changes
apps— rewritten as the first-class managed services a user orders directly (Postgres, Kubernetes, S3 bucket, …), with the high-level-API / input-control rationale.extra— rewritten as enabler modules switched on per-tenant that power those services under the hood, with the worked exampleextra/seaweedfs→apps/bucket(S3) andextra/etcd→apps/kubernetes.Scope: only the latest v1 docs (
v1.5); other versions andnextare untouched.Summary by CodeRabbit