W'xOps Core publishes platform APIs as Crossplane v2 composite resources: Git hosting, identities, PostgreSQL clusters and databases, and tenant applications with Darlane workspaces. You declare one resource, and Crossplane keeps everything behind it reconciled.
This folder is for anyone who uses, operates or builds on the platform as it stands today: the API, how to install and run it, how to onboard an
application. Where the platform is headed — core ideas, decisions, proposals, the roadmap and the development process — lives in
development-docs/.
Table of Contents
| I want to… | Start here |
|---|---|
| Learn Crossplane, OpenTofu or KCL well enough to read this repo | Learn |
| Install W'xOps Core on a cluster | Setup |
| Ship an application end to end | App onboarding |
| Know what a resource does, which fields it takes, and what the reconcile loop does for me | API reference |
| Build a portal or a tool against the API | Portal integration · Status contract |
| Understand where the platform is heading | Core ideas · Solution matrix |
| Change the platform, cut a release, or record a decision | Development docs |
Contributor onboarding for someone who hasn't used Crossplane, OpenTofu or KCL before — four short pages, each teaching one concept against a real file in this repo rather than a generic tutorial. Read only the pages you're missing.
| Doc | What it covers |
|---|---|
| Start here | Which of the four pages to read, mapped to the package you're about to touch |
| Crossplane in five minutes | XRD, XR, Composition, composed resource — walked through scm-connection end to end |
| OpenTofu and HCL, the way this repo uses them | The inline-HCL Workspace pattern scm-repository and scm-oauth-app use |
| KCL, the way this repo uses it | This repo's KCL idioms (_get, ternary chains, conditional composition) on a real slice of code |
| Your first change | A guided edit to scm-oauth-app, start to finish: schema, template, test, PR |
What each Kind accepts, what Core composes and keeps reconciled for it, and what it reports back. The schema source is package/<group>/<name>/xrd.yaml; the
API group (platform, scm, ...) is per package — see ADR-002.
| Doc | Kind | What it covers |
|---|---|---|
| Start here — the reconcile loop and every Kind | all | What you can do with an XR (create, change, pause, hold, delete), how to read status, and a catalogue of every Kind |
| gitea-user (archived) | XGiteaUser |
A Gitea user and its generated password — superseded by scm-repository |
| gitea-org (archived) | XGiteaOrg |
A Gitea organisation with visibility and metadata — superseded by scm-repository |
| gitea-team (archived) | XGiteaTeam |
A team inside an organisation, including membership — superseded by scm-repository |
| gitea-repository (archived) | XGiteaRepository |
A repository owned by an organisation — superseded by scm-repository |
| platform-database-clusters | XPlatformDatabaseCluster |
A CloudNativePG cluster with poolers, backups and Vault-seeded credentials |
| tenant-database | XTenantDatabase |
A tenant database on a shared or dedicated cluster, credentials pushed to Vault |
| tenant-app | XTenantApp |
Deployment, Service, ingress with TLS and SSO, monitoring, and the Darlane twin |
| random-password (archived) | XRandomPassword |
Utility composition, not published as a package |
| scm-connection | XScmConnection |
One Git hosting service and its credential, rendered for every other scm resource |
| scm-repository | XScmRepository |
A repository on Gitea or GitHub, created (managed) or read (observed) |
| scm-oauth-app | XScmOAuthApp |
A host-side OAuth application, with its credentials in the secret store |
| status-contract | all | Every package's status fields on one page: the absent-vs-false split, ready vs dependenciesReady |
Running W'xOps Core and building on it.
| Doc | What it covers |
|---|---|
| setup | Prerequisites and platform dependencies, providers, credentials, installing packages, and a first resource |
| app-onboarding | The golden path from picking a template to a running XTenantApp, through XScmRepository |
| portal-integration | The consumer side of the API: screen-by-screen field map, health cards, error-to-runbook wiring, and what a portal must never do |
flowchart LR
LEARN["Learn<br/>Crossplane · OpenTofu · KCL<br/>as this repo uses them"]
UG["User guide<br/>setup · app onboarding<br/>portal integration"]
API["API reference<br/>reconcile loop · every Kind<br/>status contract"]
DEV["Development docs<br/>core ideas · decisions · proposals · roadmap"]
LEARN -->|"prerequisite for"| DEV
UG -->|"fields to write,<br/>status to read"| API
DEV -->|"a core idea lands as<br/>a field on"| API
DEV -->|"every change is<br/>gated against"| API
classDef hub stroke-width:3px
class API hub
The API reference sits in the middle on purpose. A core idea — in development-docs/, since it's about where the platform is headed, not how it's used today —
becomes real when it lands as a field on a Kind. A user guide is a path through those fields. Learn is prerequisite reading for development, not a section of it
— it teaches the underlying tools, not this repo's workflow. Every development change is checked against the released API.
Core ideas, decisions, proposals, the roadmap and the development process are in development-docs/:
| Doc | What it covers |
|---|---|
| Development docs hub | Find your way, the development matrix, and where new docs go |
| Core ideas | Darlane, Guardian, multi-cluster, observability, self-service operations, knowledge architecture, security — solution matrix is the index |
| Development guide | The change loop, hooks and make targets, and the rules that bite |
| Releasing | Version axes, why a released XRD only grows, make release, CI publishing |
| ROADMAP (archived) | Phases, the deferred core, decisions made and rejected, open decisions, as of the release it describes — superseded by the RFC index |
| ADR | One committed file per decision of lasting consequence |
| RFC | One committed file per proposal, argued before it is built |
CONTRIBUTING.md |
Setup, the change loop, commit messages, and the checklist for a new package |
CLAUDE.md |
Architecture, KCL conventions, the working model, and the reference stack |