From 70883fefce4683bf4ff318ad67985191dd6b6227 Mon Sep 17 00:00:00 2001 From: James Maes Date: Sat, 26 Sep 2026 09:26:58 -0500 Subject: [PATCH 1/3] docs: add core and full quick start and feature tour (#9) --- README.md | 39 ++++++++++++++++++++++++++++----------- 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 72e899f..d4acc84 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,40 @@ # qqq-all -QQQ with every feature configured and working out of the box: every storage backend, quick search, the ESB (ActiveMQ Artemis and RabbitMQ), OIDC, and the Next dashboard. It runs in two profiles: `core` (no containers, `java -jar`) and `full` (`docker compose --profile full up`). +An evolving reference app for QQQ 4.1. The `core` profile runs locally from one jar; `full` adds external backends and services. Compose and the remaining QBit demos are in separate, unmerged work. -**Status:** under construction. qqq-all versions track QQQ and build on `4.1.0-SNAPSHOT` until QQQ 4.1 ships. See the [design](docs/design.md), the [plan](docs/plan.md), and the epic [#1](https://github.com/QRun-IO/qqq-all/issues/1). It is a local demo and reference build, not a production deployment. +**Status:** under construction. qqq-all versions track QQQ and build on `4.1.0-SNAPSHOT` until QQQ 4.1 ships. See the [design](docs/design.md), the [plan](docs/plan.md), and the epic [#1](https://github.com/QRun-IO/qqq-all/issues/1). + +## Quick start + +From the repository root, install Java 21 and Maven, then build the app and its BOM with `mvn -B -pl qqq-all-app -am verify`. This needs access to the QQQ 4.1 snapshot dependencies described in the [app guide](qqq-all-app/README.md). + +**Core:** run `java -jar qqq-all-app/target/qqq-all-app-4.1.0-SNAPSHOT.jar`. Open `http://127.0.0.1:8080/`; `/health` is the health endpoint. The app seeds its local data under `./data` on first start. Set `QQQ_ALL_PORT` or `QQQ_ALL_DATA_DIR` to change those defaults. Core uses mock demo identities, so keep it on the loopback address. + +**Full:** first provision PostgreSQL, MySQL, a MongoDB replica set, MinIO, SFTP, Artemis, RabbitMQ, Mailpit, Keycloak, and the required schemas and bucket. Set the `QQQ_ALL_*` variables listed in the [app guide](qqq-all-app/README.md). Then run `QQQ_ALL_PROFILE=full QQQ_ALL_BIND_HOST=127.0.0.1 java -jar qqq-all-app/target/qqq-all-app-4.1.0-SNAPSHOT.jar`. Full does not start those services itself; the Compose setup is still in C6. Keep `QQQ_ALL_BIND_HOST` on loopback for a local demo. + +## Feature tour + +| Feature | Where to find it | +|---|---| +| Next dashboard and health | The root page and `/health` in both profiles. | +| Local storage | Seeded `customer` and `order` tables in H2, `orderLine` in SQLite, and `product` JSON files under `./data/files` in core. | +| Event bus | An `order` insert or update publishes to the embedded Artemis `orderEvents` topic and triggers `syncOrder` in core. | +| External storage | Full adds `warehouseCustomer` (PostgreSQL), `supplierOrder` (MySQL), `shipment` (MongoDB), `document` (MinIO S3), and `importFile` (SFTP). | +| Messaging and email | Full uses external Artemis for `orderEvents`, publishes completed `syncOrder` events to RabbitMQ `orderSyncEvents`, and configures Mailpit SMTP. | +| Authentication and permissions | Core has mock Admin and Demo User identities. Full uses Keycloak OIDC and maps realm roles through `qbit-user-role-permissions`; unknown roles get no permissions. | + +The tour reflects code already on `develop`. Quick search and the other QBit examples are being added in C5; the Compose/image quick start is being added in C6. + +## Local-demo limits + +This is a local demo and reference build, not a production deployment. Core uses mock authentication and a nonpersistent embedded broker. A production installation needs its own DNS, TLS termination, backups and restore testing, monitoring and alerting, and highly available brokers. Review authentication, credentials, data persistence, and network exposure before deploying beyond a local machine. ## Modules | Module | Purpose | |---|---| | `qqq-all-bom` | One tested version set for QQQ, the ESB, the Next dashboard, the included qBits, JDBC drivers, and broker clients | -| `qqq-all-app` | The reference application with every backend, qBit, and the ESB wired, plus seeded demo data | - -## Build - -Requires Java 21 and Maven. - -```bash -mvn -B verify -``` +| `qqq-all-app` | The core reference app and full-profile external-service wiring, plus seeded demo data | ## Contributing -- 2.54.0 From ee0c60dcecccbfc6fc9325e09b643aa9119a576f Mon Sep 17 00:00:00 2001 From: James Maes Date: Sat, 26 Sep 2026 10:21:46 -0500 Subject: [PATCH 2/3] docs: correct qqq-all build and seed behavior (#9) --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d4acc84..cf32ab0 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ An evolving reference app for QQQ 4.1. The `core` profile runs locally from one ## Quick start -From the repository root, install Java 21 and Maven, then build the app and its BOM with `mvn -B -pl qqq-all-app -am verify`. This needs access to the QQQ 4.1 snapshot dependencies described in the [app guide](qqq-all-app/README.md). +From the repository root, install Java 21 and Maven, then build the app and its BOM with `mvn -B verify`. This needs access to the QQQ 4.1 snapshot dependencies described in the [app guide](qqq-all-app/README.md). -**Core:** run `java -jar qqq-all-app/target/qqq-all-app-4.1.0-SNAPSHOT.jar`. Open `http://127.0.0.1:8080/`; `/health` is the health endpoint. The app seeds its local data under `./data` on first start. Set `QQQ_ALL_PORT` or `QQQ_ALL_DATA_DIR` to change those defaults. Core uses mock demo identities, so keep it on the loopback address. +**Core:** run `java -jar qqq-all-app/target/qqq-all-app-4.1.0-SNAPSHOT.jar`. Open `http://127.0.0.1:8080/`; `/health` is the health endpoint. The app stores local data under `./data` and merges sample customer and order rows on every start, which can reset edits to those rows. Set `QQQ_ALL_PORT` or `QQQ_ALL_DATA_DIR` to change those defaults. Core uses mock demo identities, so keep it on the loopback address. **Full:** first provision PostgreSQL, MySQL, a MongoDB replica set, MinIO, SFTP, Artemis, RabbitMQ, Mailpit, Keycloak, and the required schemas and bucket. Set the `QQQ_ALL_*` variables listed in the [app guide](qqq-all-app/README.md). Then run `QQQ_ALL_PROFILE=full QQQ_ALL_BIND_HOST=127.0.0.1 java -jar qqq-all-app/target/qqq-all-app-4.1.0-SNAPSHOT.jar`. Full does not start those services itself; the Compose setup is still in C6. Keep `QQQ_ALL_BIND_HOST` on loopback for a local demo. -- 2.54.0 From 53913bd8dfe76287ce84bd3734bf638b44cb7f3f Mon Sep 17 00:00:00 2001 From: James Maes Date: Sat, 26 Sep 2026 10:55:51 -0500 Subject: [PATCH 3/3] docs: clarify demo logins and webhook flow (#9) --- README.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 709189f..4550814 100644 --- a/README.md +++ b/README.md @@ -10,21 +10,30 @@ Install Java 21 and Maven, then build the app and its BOM from the repository ro mvn -B verify ``` -Run core from the packaged jar, or use Compose for either profile: +Run core from the packaged jar: ```bash java -jar qqq-all-app/target/qqq-all-app.jar -# Or, after copying the local demo settings: -cp .env.example .env -docker compose --profile core up --build --wait -# Use --profile full instead to start all external services. ``` -Open `http://127.0.0.1:8080/` for the dashboard and `/health` for status. The full profile starts PostgreSQL, MySQL, MongoDB, MinIO, SFTP, OpenSearch, Artemis, RabbitMQ, Mailpit, and Keycloak. Its demo logins are `demo-admin` and `demo-user`; their sample passwords are in [the demo realm](infra/keycloak/realm.json), while the OIDC client secret comes from your local `.env`. The browser issuer is `http://keycloak.localhost:8081`; make that name resolve to loopback if your host does not already. Compose publishes demo ports on host loopback. The [app guide](qqq-all-app/README.md) lists the environment contract and broker-management check. +Or copy the local demo settings and run core with Compose: + +```bash +cp .env.example .env +docker compose --profile core up --build --wait +``` + +To run full instead, stop core first, then use the same `.env` (or copy `.env.example` if starting with full): + +```bash +docker compose --profile full up --build --wait +``` + +Open `http://127.0.0.1:8080/` for the dashboard and `/health` for status. The full profile starts PostgreSQL, MySQL, MongoDB, MinIO, SFTP, OpenSearch, Artemis, RabbitMQ, Mailpit, and Keycloak. Its demo logins are `demo-admin` and `demo-user`; their sample passwords and the OIDC client secret come from your local `.env` (copied from [.env.example](.env.example)). The browser issuer is `http://keycloak.localhost:8081`; make that name resolve to loopback if your host does not already. Compose publishes demo ports on host loopback. The [app guide](qqq-all-app/README.md) lists the environment contract and broker-management check. ## Explore the app -Core seeds customers and orders in H2, order lines in SQLite, and product files under `./data`. Insert an order as Admin to publish an Artemis `orderEvents` message and trigger `syncOrder`; inspect its process trace and the demo webhook receipt. Core's mock Demo User can read but cannot edit webhook destinations or invoke delivery. Sample customer and order rows are merged on every start, so edits to those rows can be reset. +Core seeds customers and orders in H2, order lines in SQLite, and product files under `./data`. Insert an order as Admin to publish an Artemis `orderEvents` message and trigger `syncOrder`; inspect its process trace. Run `SendWebhookEvent` as Admin, then inspect the demo webhook receipt. Core's mock Demo User can read but cannot edit webhook destinations or invoke delivery. Sample customer and order rows are merged on every start, so edits to those rows can be reset. Full adds sample tables on PostgreSQL, MySQL, MongoDB, MinIO S3, and SFTP. It includes OpenSearch customer quick search, table views, process tracing, workflows, geo addresses, SFTP import, and webhook administration with Keycloak role permissions. The `syncOrder` completion publication to RabbitMQ is configured in metadata and depends on QQQ ESB [Task 9](https://github.com/QRun-IO/qqq/pull/786) landing in QQQ 4.1; the app does not publish it through a separate workaround. -- 2.54.0