Whoobe - release documentation#
The documentation in this folder describes the product as it is delivered and operated. Everything here has been
checked against the code at the time of the last reorganisation (see Status); the design history of the
project stays in ../plans and is deliberately not part of a release.
Aligned to release: v0.3.3 (2026-10-27) - see release-process.md
0.3.3 shows the tokens of every AI answer and can record them per person, off by default, with a retention period for the AI history (release notes); 0.3.2 is a patch of 0.3.0 that removes the build tools from the publisher image (release notes); 0.3.1 brought security updates (release notes). New in 0.3.0, Operate (see the release notes): fleet commands over many workspaces, install from released
images, the private profile for a network with no route to the internet, custom fonts, a site specification any LLM can write, the Generate
Website Wizard, Kits, and the disclosure policy. Earlier releases: 0.2.0 (Conduct: audit log, two-factor
authentication, single sign-on, object events), 0.1.1, 0.1.0.
Deployment model. One workspace per organisation. Divisions of the same entity share a workspace and are told apart with roles; different companies or legal entities get separate workspaces. Whoobe is not a shared multi-tenant platform (why).
1. Start here#
| If you want to... | Read |
|---|---|
| understand what Whoobe is and why a platform like it | What Whoobe is (one page) |
| see what it can do for you, with everyday examples | What you can do with Whoobe |
| judge fit, cost and limits | Full overview |
| understand how it is built and why | Architecture overview, design decisions |
| read what is written for your role | Documentation by role: CEO, IT manager, operators, security and compliance, marketing, data owners, developers |
| learn to use it | User manual |
| install it | Operations: start here |
2. The pillars#
The detailed documentation is organised by what Whoobe does. Each pillar has an index page.
| Pillar | What it is | Index |
|---|---|---|
| Content | Websites, pages, snippets, themes, languages, documentation sites, publishing to sites, apps and headless | content/ |
| Data (PIM, MDM) | Data Classes and Objects, relations, languages, publish workflow, import from Pimcore, using data in pages and apps | data/ |
| Communication | Integrations, Automations, the Client Hub (API clients), forms and mail | communication/ |
| DAM | The media library: storage, folders, visibility, transforms, CDN mirror | dam/ |
| AI | Generating pages, snippets and images, translation, Figma import; your provider, your key | ai/ |
| Settings | Configuration in the dashboard and in the environment | settings/ |
| Security | Threat model, findings, data protection, test evidence, supply chain | security/ |
| Operations | Install, configure, back up, upgrade, observe | operations/ |
| Guides | The user manual and an index of every how-to | guides/ |
3. Other sections#
| Section | What is in it |
|---|---|
overview/ |
What Whoobe is, what you can do with it, the full overview (what it does and does not do, costs, fit, by role), the dated executive summary |
architecture/ |
Architecture overview, data and storage, authentication and authorization, and the design decisions |
by-role/ |
Reading paths for CEO, IT manager, operators, security and compliance, marketing, data owners, developers |
api/ |
API reference and openapi.yaml, both generated from one route table by gen-api-docs.py |
whoobe-history.md |
The story of Whoobe |
credits.md |
Thanks to the open-source projects Whoobe is built with and works with; the legal record is THIRD_PARTY_NOTICES.md |
community/ |
Why sponsor and why contribute to open-source projects, and how to help Whoobe; how Whoobe evolves: what comes next, what is built only when funded, and the rule that the code stays MIT |
release-process.md |
How a release is made: versions, support policy, release gates, procedure |
release-notes-0.3.3.md, 0.3.2, 0.3.1, 0.3.0, 0.2.0, 0.1.1, 0.1.0 |
What each release contains, behaviour changes to check before upgrading, known limits |
Reading paths. Architect: architecture overview, data and storage, authentication, capacity. DevOps: creating workspaces, configuration reference, secrets and keys, backup/DR, upgrade, observability. Security / compliance: threat model, status summary and findings, data protection, supply chain, encryption. More in documentation by role.
What is not here#
docs/plans/- design documents and implementation plans, written before or while a feature was built. They explain why something is the way it is, and many code comments point to them, but they are not kept in step with the code and some describe work that was changed or not done. Read them as history.- Early notes and one-off documents at the top of
docs/(initial notes and plan, the DAM implementation plan, Studio integration notes, an exported console log, a Figma export).
Rules for this folder#
- Only current documents. A document is added here when it describes behaviour that exists in the code, and it
leaves (back to
plans/, or deleted) when it stops being true. - Facts that can be checked are checked. Paths, commands, environment variables, screen labels and route lists
in these files must exist in the repository. The API reference and OpenAPI file are generated:
edit the route table in
api/gen-api-docs.pyand runpython3 docs/release/api/gen-api-docs.py. A route added to core-api without an entry there leaves the API documentation behind; compare withscripts/security/routes.expected.json(all 228 core-api routes are documented, checked byscripts/release/check-docs.py). The same script fails when an environment variable read by the services or listed in.env.exampleis missing from the configuration reference. - Changes are logged in the root
CHANGES.md, as for any other file.
Status#
Reorganised on 2026-10-05; technical layer (architecture, operations, security reviews) added on 2026-10-09; restructured by pillar, with the platform overview,
design decisions, reading paths by role and the pillars Data, AI and Settings, on 2026-10-13.
The documentation gate of the release (./scripts/release.sh check, scripts/release/check-docs.py) passes: every core-api
route documented, no broken link or quoted repository path, every environment variable documented.
What a documentation release still needs#
| Item | State | Owner / next step |
|---|---|---|
| Alignment line (the release this documentation matches) | set by scripts/release.sh prepare |
release manager |
Technical set for architects, DevOps and security (architecture/, operations/, security/) |
written 2026-10-09 from the code; statements that depend on running systems (TLS on a live host, upgrade, restore, load, multi-replica) are marked as untested | review by someone other than the author; rehearse the runbooks once (backup, upgrade) |
| Findings found by the review: F-055 to F-058 | recorded in security/findings.md; fixed 2026-10-09 (see the status summary, section 3) |
none |
| Security status summary, DAST, manual security checklist | summary updated 2026-10-23; DAST run on the release candidate (run 39934951757, all jobs green); the manual checklist was not repeated for the features added since 0.2.0 (see the status summary, section 3) | run the checklist on the release commit, or accept in the release notes |
| SBOM | scripts/release/sbom.sh works (CycloneDX, 669 components in the source tree); not attached automatically |
attach to the GitHub Release; automate in release.yml |
| Image digests, signatures, provenance | published by release.yml on a tag: amd64 and arm64 images on ghcr.io, signed by digest, with a source SBOM on the draft GitHub Release (v0.1.1, v0.2.0) |
release process section 7 |
Bare-metal guides (operations/deployment.md, miniguide-deployment.md) |
flagged as not re-verified; the container workspace is the tested path | rewrite or retire |
| User manual | partial by design: chapters listed in its table of contents are not written; no App Mode, thumbnail capture, documentation-site, form-upload chapters (the guides cover them) | write after the release |
content/headless-sdk.md, content/dynamic-website-paths.md, publishing guides |
names checked, not read line by line | review |
| Executive summary | positioning text dated 2026-09-18; not a technical reference | refresh before external use |
| Runbooks: restore, upgrade, workspace removal and re-creation | restore of a destroyed workspace and the upgrade from the previous release are run by scripts (rehearse.sh, upgrade-test.sh); the public host was upgraded by hand 2026-10-19; not run on a customer's host and data |
the operator rehearses once and notes the date |
| Generated documentation sites | the product can publish this folder as a documentation site (Markdown, index, search); published at https://docs.whoobe.dev from the site "whoobe docs release" (re-upload the folder to the DAM, then DOCS_WEBSITE_ID=<id> scripts/site/pages/deploy.sh docs: generated with whoobe-publish --kind docs --strict and uploaded to Cloudflare Pages) |
regenerate after each release |
| Languages | English only |
Last updated