qqq

Run QQQ with Next

Start with an editable Java application and seeded local data, then make it your own.

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. Keep ports 3000 and 8000 free. The launcher checks Java, Git, curl, unzip and Docker before starting.

Maven Wrapper verifies its pinned ZIP checksum; unzip extracts that distribution. The wrapper and prebuilt Next container mean no Maven or Node.js installation, manual database setup, or account is needed.

Start the app

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

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

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 0.1.0. The first run downloads the source, Maven, dependencies and dashboard image.

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

Startup target and measured run

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

The 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. It started without app source, Maven or Docker caches, browser application cache, or registry login, and included the bootstrap, clone, all application downloads, compilation, startup and first usable page. Prerequisite installation was excluded. Your connection and machine affect the result; 90 seconds is a target, not a guarantee. See the benchmark conditions.

Edit and rerun

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

Bash
cd qqq-sample
./quickstart.sh

Use your chosen directory name if you supplied one. The launcher recompiles your changes; restarting recreates the H2 sample data. The source stays on disk. Check quickstart.log in the checkout for build and application output.

Framework contributors and Material

The framework-contributor workflow keeps the full framework build, acceptance tests and Material Dashboard 0.41.0 instructions separate. Next is the default for this app quickstart and remains a compatible preview; widget parity limitations and the missing form summary alongside a process record list remain.

Build your own application

Start with the dependency setup, table guide, and 4.0 migration checklist. The app starter is a separate MySQL learning application.