qqq-all/README.md

qqq-all

A runnable reference app for QQQ 4.1 with two profiles: core uses local storage and embedded Artemis; full adds external storage, RabbitMQ, OpenSearch quick search, Keycloak, Mailpit, and the included qbits. It is a local demo under construction while QQQ 4.1 finishes. See the design, plan, and epic #1.

The stack pins public Next 1.0.0-RC.8 for application testing. The owner approved an RC carrying its documented Firefox/WebKit/tablet failures, report/query and input parity gaps, sub-path hosting, real Google Drive verification, and visual-approval limitations. These remain open; passing qqq-all HTTP smoke checks do not establish browser parity or GA acceptance. See the RC8 scope and approval.

Quick start

Install Java 21 and Maven, then build the app and its BOM from the repository root:

mvn -B verify

Run core from the packaged jar:

java -jar qqq-all-app/target/qqq-all-app.jar

Or copy the local demo settings and run core with Compose:

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):

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). 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 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. 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 event publishes to RabbitMQ through QQQ ESB metadata. The full smoke check exercises this round trip with the public QQQ snapshot dependencies; final release acceptance must repeat it with released dependencies.

To stop the full stack, run docker compose --profile full down. Add --volumes only when you intend to erase demo data. For a fresh Artemis volume, the configured login is required; old volumes created for anonymous access should be recreated. This reference stack uses demo credentials and is not a production deployment.

CI runs .gitea/workflows/build.yaml through the shared KofTwentyTwo/ci-workflows container workflow: script unit tests, mvn verify, and the packaged core HTTP smoke check on every push, then the image build and Trivy scan. Pushes to develop publish git.kof22.com/qrun-io/qqq-all (ci-<sha>-run-<n> and develop). The full Compose smoke check runs locally with python3 scripts/run_full_smoke.py.

The 4.1.0 release procedure describes the separate Maven parent/BOM publication path. The GitHub release workflow that called the retired qqq-orb was removed; a versioned release path on Gitea is not defined yet.

Contributing and license

See CONTRIBUTING.md, the Code of Conduct, and the security policy. Licensed under Apache-2.0; see LICENSE and NOTICE.

The application JAR includes exact copies of these project documents under META-INF/qqq-all/, separate from dependency notices. The container also includes them at /app/LICENSE and /app/NOTICE. PackagedNoticesIT checks the shaded JAR's project documents against the root files during the existing mvn verify lifecycle.