Quickstart

> These instructions are for stable QQQ 4.0. For the prerelease without Docker, use the QQQ 4.1 RC1 quickstart.

Run an editable local app

The quickstart clones the sample application source and opens it with the Next dashboard. Edit the Java application locally while consuming published QQQ 4.0.0 dependencies. The Next dashboard remains a compatible preview; widget parity limitations are separate from the Material Dashboard 0.41.0 workflow below. Multi-component process steps that pair a primary record list with a form summary currently omit the accompanying summary (#645).

Prerequisites

Use macOS, Linux or Windows WSL with a Java 21 JDK, Git, curl, unzip, Bash and a running Docker daemon. Run these commands in Bash, not native PowerShell. The launcher checks Java, the compiler, Git, curl, unzip and Docker before starting. Maven Wrapper verifies its pinned ZIP checksum; unzip extracts that distribution. Keep ports 3000 and 8000 free. You do not need to install Maven or Node.js, configure a database, or create an account: the checkout includes Maven Wrapper, the dashboard uses a prebuilt container, and the app seeds a local H2 database.

Start the app

Download the launcher to a local file, then run it:

curl --fail --location --output quickstart.sh https://raw.githubusercontent.com/QRun-IO/qqq/quickstart-4.0.0/quickstart.sh
bash quickstart.sh

By default, this creates a new qqq-sample directory. To choose another new directory, use bash quickstart.sh my-qqq-app instead of the second command. The launcher checks out the signed quickstart-4.0.0 source tag, compiles only the sample against published QQQ 4.0.0, and starts the prebuilt Next dashboard ghcr.io/qrun-io/qqq-frontend-next:0.1.0. The first run downloads the app source, Maven, dependencies and dashboard image.

Open localhost:3000/app/person if the browser does not open automatically. Explore the seeded Person records. The Java backend runs on port 8000; the Next dashboard runs on port 3000. Mock authentication and synthetic sample data are for local exploration, not a production authentication setup.

Startup target and measured run

The target is a usable local app within 90 seconds after prerequisites are installed and Docker is running. A public cold-start check on 2026-09-24 reached the real seeded Next page in 43.6 seconds.

That run used a fresh Ubuntu 26.04 aarch64 VM with 4 vCPUs and 6 GiB RAM on a Mac, with Java 21, Git and Docker preinstalled. Chrome ran on the host through local port forwarding. There was no prior app checkout, Maven Wrapper/dependency cache, Docker image/layer cache, browser application cache or registry login. The measurement included the bootstrap download, clone, all application downloads, compilation, startup and the first usable page. Prerequisite installation was excluded. Download speed and machine resources affect your result; 90 seconds is a target, not a guarantee.

Edit and rerun

Press Ctrl+C in the launcher terminal to stop the app and dashboard container it started. Edit Java files under qqq-sample/qqq-sample-project/src/main/java, then run the launcher from the checkout:

cd qqq-sample
./quickstart.sh

Use your chosen directory name if you supplied one. Rerunning recompiles the application; restarting recreates the in-memory sample data. The editable checkout remains on disk. Build and application output is in quickstart.log in the checkout. If a prerequisite, download or build fails, follow the launcher message and inspect that log.

Framework contributor and Material workflow

Use this separate path when changing the framework itself or running its full test suite. It builds the framework source and serves Material Dashboard 0.41.0 at port 8000; it is not required for the app-source quickstart above.

Build from framework source

git clone https://github.com/QRun-IO/qqq.git
cd qqq
git checkout v4.0.0
mvn clean install
mvn -f qqq-sample-project/pom.xml -Pacceptance-tests -Dqqq.frontend.material-dashboard.version=0.41.0 clean verify
mvn -f qqq-sample-project/pom.xml -Dqqq.frontend.material-dashboard.version=0.41.0 exec:java \
  -Dexec.mainClass=com.kingsrook.sampleapp.SampleJavalinServer \
  -Dqqq.sample.mockAuthentication=true

The sample is a separate Maven project, outside the root reactor. Building the framework first supplies its matching dependencies. Framework integration tests require Docker; sample acceptance also needs a locally installed Chrome or Chrome for Testing. Allow time for the first dependency download and full build.

Follow the sample README for the server command and authentication settings for that source revision. The server class is com.kingsrook.sampleapp.SampleJavalinServer, and the local dashboard is at http://localhost:8000/.

Explore the Material sample

Open People App, then Greetings App, then Person. Inspect a seeded record and the Greet Interactive process. The H2 database is temporary sample data; restarting the sample recreates it. Use local mock authentication only with sample data, and configure real authentication before exposing an application.

Sample startup and acceptance

Run these checks from the repository root of the v4.0.0 checkout:

mvn clean install
mvn -f qqq-sample-project/pom.xml -Pacceptance-tests -Dqqq.frontend.material-dashboard.version=0.41.0 clean verify
python3 qqq-sample-project/verify-feature-coverage.py --report-only

The acceptance profile needs Java 21, Docker and a locally installed Chrome or Chrome for Testing. It runs browser, packaged-launcher and CLI checks plus disposable MySQL, PostgreSQL and MongoDB fixtures. The running application still uses seeded H2; provider integration tests are separate from its interactive examples. The tests own their servers, browser profile and containers. No downstream application, shared database, provider account or external sign-off is required for these checks.

The sample uses the SampleJavalinServer launch command and local mock-authentication option shown above. ConfigFileBasedSampleJavalinServer loads the same application and bundled metadata, with an optional directory containing only additional YAML/JSON metadata. Invalid files and duplicate table names fail startup; adding metadata does not create SQL tables. IsolatedSpaServer serves a public SPA at / and an authenticated private SPA at /private/. Use the matching sample README for its packaged-JAR commands and public demonstration credentials; these modes are not production authentication configurations.

Ordinary mvn -f qqq-sample-project/pom.xml test is a lightweight unit-test run, not the acceptance profile. Use the profile for the sample's verify or install, because its coverage gate includes packaged launchers. The report-only ledger command reports outstanding gaps; it does not certify complete coverage. The 48 source-coverage groups and separate train.bom coverage group (#627) are deferred beyond 4.0 under #534; the ledger continues to report them separately from release acceptance.

To verify the public versions from a clean committed checkout with Python 3.12 or later:

python3 qqq-sample-project/verify-published.py 4.0.0 --material-version 0.41.0

This uses a new Maven cache and runs the sample acceptance profile against published artifacts. Its feature-ledger report does not certify the deferred groups. Use --require-complete-coverage only when that separate comprehensive gate is required.

Start your own application

The app starter contains a MySQL schema, environment settings, and a runnable server. Verify its dependency version against release status. The qctl production scaffold is maintained separately and is not one of the three QBit templates delivered with 4.0.

Continue with core concepts and tables.