Quick Start

This guide brings StackRivet up locally: backend, health check and the Vue admin UI. For a fuller explanation of every setting, see Installation.

Prerequisites

• JDK 21 (the default supported major; major framework upgrades use dedicated branches)
• Maven 3.9+
• Docker — to run MySQL and Redis locally
• Node.js 24 + pnpm 11 — to run the admin UI

0. Get the code

Keep the backend and admin UI as sibling directories:

git clone https://github.com/zkmall/stackrivet-server.git
git clone https://github.com/zkmall/stackrivet-admin-ui.git
cd stackrivet-server

Gitee mirrors are available in Installation.

1. Start the data stores

The default profile uses MySQL + Redis. Redis backs JWT revocation and the Actuator health check, so it is required.

docker compose up -d mysql redis

Add postgres only if you set STACKRIVET_DB_VENDOR=postgresql; add minio only if you set STACKRIVET_STORAGE_TYPE=s3. See Configuration for the common environment variables.

2. Build the reactor

The backend is a modular monolith of 16 Maven modules. Build them all once:

./mvnw -pl stackrivet-app -am install -DskipTests

3. Run the application

stackrivet-app is the Spring Boot entry point that assembles every business module into the runnable application:

./mvnw -pl stackrivet-app spring-boot:run

4. Confirm the backend

Once the app has started, confirm the management health endpoint:

curl http://127.0.0.1:9090/actuator/health

It should return {"status":"UP"}. OpenAPI is also available, but it is protected; sign in first and use a bearer token when calling /v3/api-docs.

5. Run the admin UI

Keep the backend running. In a second terminal, start the frontend from the stackrivet-admin-ui repository. Vite proxies /api/* to the backend on port 8080; health checks stay on the separate management port 9090. Requires Node 24; get pnpm 11 via Corepack:

cd ../stackrivet-admin-ui
corepack enable && corepack prepare pnpm@11 --activate   # if you don't already have pnpm 11
pnpm install
pnpm dev          # http://127.0.0.1:5173/

6. Log in

Open http://127.0.0.1:5173/ and sign in with the local development seed account:

• Username: admin
• Password: stackrivet2026

You should land on the admin dashboard — that is StackRivet running end to end.

Local development only: these credentials are created by the database migration for a fresh local database. They are not hosted-demo credentials. Never expose or deploy an instance while it retains the seed password; production-class profiles reject it and require rotation (see Deployment). Follow the instructions shown on the hosted demo sign-in page for demo access.

If something fails

Symptom	Check
MySQL or Redis is not ready	docker compose ps in stackrivet-server
Backend cannot bind to 8080	Stop the old process using that port
Admin UI shows API errors	Confirm the backend is still running on 127.0.0.1:8080
pnpm is missing	Run the Corepack command above, then retry pnpm install

Next steps

• Project Structure — how the repositories and modules fit together.
• Generate your first module — create a small table and generate a governed module.

Continue with object storage and deployment after the first module works.