A host should take the CMS whole from this qbit: its tables, its help and its schema. Two things forced a host to write CMS material of its own; both are fixed here. - Help: help/qbit-cms.yaml (643 entries) covers every app, home, table, section, field, child list and value list. The producer registers it when the host uses the default names. CmsHelpTest holds it to the core's coverage gate (HelpBundleAssertions) and to every section. - Schema: the first guard changeset (1.0.0-guard-existing-tables) no longer has runAlways. It rewrote its DATABASECHANGELOG row on every migration, so a second migration was never a no-op and a rollback by count began with it; a host whose migrations must be repeatable had to copy the tables. It runs once now, with validCheckSum: ANY so an install that already ran it migrates on unchanged. This changes a released changeset on purpose; CmsInstallTest.testRerunIsNoop covers a second run and an install the earlier version recorded. - Homes: text sizes in rem (labels 0.875rem instead of 13px), so they follow the reader's text size. Tests: 40, Checkstyle 0, guardrails and coverage checks pass. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
QBit CMS
QQQ QBit: a headless CMS (sites, pages, menus, blog, media, projects, photos and publishing) as standard QQQ tables.
Status: design approved in QRun-IO/qqq#1083 (see docs/DESIGN.md). CORE, MEDIA, BLOG, PROJECTS and PHOTOS are implemented as tables with their admin screens. File upload, storage and renditions, the publishing processes, the content stream and the Site API are not built yet; PUBLISHING and STREAM are next.
The CMS is extracted from the kof22 website, which runs it in production. Its data lives in ordinary QQQ tables in your own database, secured by QQQ permissions. It brings an admin app with one home per area, and a schema you run with your own Liquibase.
Requirements
- Java 21.
- QQQ 4.1 (built against
4.1.0-RC.4) with an RDBMS backend: PostgreSQL 14+ in production, H2 for tests. - QQQ Next UI 1.0 (
1.0.0-RC.14or later). Material is not supported. - Liquibase in your migration pipeline (or the reference DDL in
docs/ddl/postgres.sql).
Install
-
Add the dependency
com.kingsrook.qbits:qbit-cms(once released). -
Run the schema. Put the qbit jar on your Liquibase classpath and include its changelog. Set its properties before the include (the first definition wins):
databaseChangeLog: - property: { name: cms.tablePrefix, value: cms_ } # must equal CmsQBitConfig.tableNamePrefix - property: { name: cms.features, value: "CORE,MEDIA,BLOG" } # the features you install (default: all) - include: { file: qbit-cms/db/changelog/qbit-cms.changelog.yaml }The changelog is safe to include in a migration that must be repeatable: a second run changes nothing, the migration history included. The changelog never touches a table it did not create. If a table with one of its names already exists, it halts with a message telling you to choose another prefix. It seeds only generic reference data (redirect, page, section, media and blog types); set
cms.seedReferenceDatatofalseto skip that. -
Produce the qbit after your backends (and the parent app, if any) are on the instance:
new CmsQBitProducer() .withQBitConfig(new CmsQBitConfig() .withBackendName("rdbms") .withRole("cms-admins", CmsRole.ADMIN) .withRole("cms-editors", CmsRole.EDITOR)) .produce(qInstance); -
Grant permissions from your authentication customizer:
CmsSecurity.applySessionPermissions(session, userGroups, config).
At startup the producer checks that the changelog ran for every enabled feature and that the tables exist. startupMode FAIL_FAST (the default) refuses to start and lists what is missing. DEGRADED starts and shows the problem on the CMS home. SKIP does not check (unit tests without a database).
Configuration reference (CmsQBitConfig)
| Setting | Default | Meaning |
|---|---|---|
backendName |
required | The RDBMS backend for every CMS table |
tableNamePrefix |
cms_ |
Table name prefix (QQQ and SQL names are equal); must equal the changelog's cms.tablePrefix |
namePrefix |
cms |
Prefix of app and widget names (cmsPages, cmsPagesHome) |
permissionBaseName |
cms |
Base of qbit-wide permissions (cms.admin, cms.publish) |
features |
every available feature | CmsFeature set; CORE is required, and a feature this version does not implement yet is rejected |
appName, appLabel, parentAppName |
cms, CMS, none |
The top app and where it nests in your app tree |
openReads |
false |
When true, reading CMS tables needs no permission (writes always do) |
startupMode |
FAIL_FAST |
FAIL_FAST, DEGRADED or SKIP (see above) |
roleMapping |
empty | Identity-provider group name to CmsRole |
A namespace (withNamespace("siteTwo")) fills in all three prefixes for a second install in the same instance (site_two_page, siteTwoPages, site_two.admin).
Features
| Feature | Tables | Status |
|---|---|---|
CORE |
site, domain, redirect, redirect type, page, page type, page section, page section type, snippet, menu, menu item | available |
MEDIA |
media, media type | available: a media record points at a file by its address; upload, storage and renditions are not built yet |
BLOG (needs MEDIA) |
blog, blog type, author, blog tag, blog post, blog post tag, blog post media, related version | available |
PROJECTS (needs MEDIA) |
project category, project, project update | available |
PHOTOS (needs MEDIA) |
album folder, photo album, photo, photo tag, photo tag link | available |
PUBLISHING, STREAM, DATA_HEALTH_RULES |
see the design | planned |
A feature that is off produces no tables, and its changesets are skipped until a later migration run names it in cms.features. Every content feature needs CORE, and blogs, projects and photos need MEDIA; a feature whose needs are not named installs nothing. What links two features (a related version of a project, a photo album of a project) keeps its column either way and gets its lookup, its list on the parent record and its foreign key only when both features are on.
Fixed lists (rendition format, cache class, content channel, content format, version status, project status) are possible-value sources named with the table prefix, for example cms_project_status. A write with a value that is not on the list is refused with an error on the record, and the database has a check constraint on the same column.
The admin
The qbit adds one app (CMS) with a home, and one sub-app per area, each with its own home:
- Sites: sites (domains are a list on each site) and redirects; Settings has redirect types.
- Pages: pages (sections and child pages are lists on each page) and snippets; Settings has page types and page section types.
- Navigation: menus (items are a list on each menu).
- Media: the media library; Settings has media types (upload rules, renditions, required text, cache and storage settings).
- Blogs: blog posts (tags, media and related versions are lists on each post), blogs (their tags are a list on each blog) and authors; Settings has blog types.
- Projects: projects (updates, photo albums and related versions are lists on each project) and project categories.
- Photos: photo albums (photos are a list on each album), album folders and photo tags.
Fields that hold an image's or a file's address show it as a preview (QQQ's file preview).
The nav shows only main tables and reference data; child tables are edited on their parents' records. Each home shows only real data read as the current user: counts, drafts, inactive rows and recently changed records, readable at any width in light and dark mode. The qbit never sets the instance's home app.
Help
The qbit ships its own help for every app, home, table, section, field, child list and value list (help/qbit-cms.yaml). The producer registers it when you use the default names (cms_, cms); a host that has the QQQ help tables then shows it with nothing to write. With your own prefixes, write your own bundle from it. Bulk screens that QQQ generates per table are the host's, as for any table.
Permissions
Every CMS table has QQQ permission rules. The table permissions are <table>.read, .insert, .edit and .delete (for example cms_page.edit). The qbit-wide permissions are cms.admin and cms.publish.
| Role | Grants |
|---|---|
ADMIN |
everything, including reference data, cms.admin and cms.publish |
EDITOR |
read everything; write content tables |
PUBLISHER |
EDITOR plus cms.publish |
DRAFTER |
read everything; insert and edit content (no deletes, no publishing) |
VIEWER |
read everything |
The qbit is built for QQQ core permission enforcement (qInstance.setEnforcePermissionsInCoreActions(true), the default from QQQ 4.2).
Operational tables
All CMS data is in normal, visible QQQ tables. Nothing is hidden and there is no side store. The schema is in docs/ddl/postgres.sql (generated from the changelog).
Upgrading
Read the CHANGELOG's "Schema changes" before deploying. Run your migrations before the new app version. Released changesets never change; new versions only append changesets.
Adopting in another app
Follow the QQQ adoption checklist once the first release is published.
Build
./mvnw verify
Always use the Maven wrapper (Maven 3.9.11); Maven 3.10 cannot read the parent POM. The PostgreSQL tests use Testcontainers and are skipped when Docker is not available.