Installation

This is the complete local setup: prerequisites, getting the code, and running both the backend and the Vue admin UI. If you just want the shortest path to a working local stack, the Quick Start is shorter.

Prerequisites

Tool	Version	For
JDK	21	Backend (required runtime; release checks also cover JDK 25 forward compatibility)
Maven	3.9+	Building the backend
Docker	any recent	MySQL + Redis (and optionally PostgreSQL / MinIO)
Node.js	24 (`>=24 <27`)	Admin UI
pnpm	11	Admin UI package manager

Get the code

StackRivet is a multi-repository workspace: the backend and the admin UI are independent git repositories that you clone side by side. (This mirrors the project’s “not a monorepo” structure — each repo has its own release cycle and license.)

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

Gitee mirrors are also available:

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

Keep the two repositories as siblings in the same parent folder; the admin UI expects the backend next to it.

1. Start the data stores

From stackrivet-server, bring up MySQL and Redis. Redis backs JWT revocation and the Actuator health check, so it is required.

cd stackrivet-server
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.

2. Build and run the backend

./mvnw -pl stackrivet-app -am install -DskipTests # build the app and its reactor dependencies once
./mvnw -pl stackrivet-app spring-boot:run # run the Spring Boot app

The API comes up on port 8080. Confirm the backend through the management health endpoint:

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

It should return {"status":"UP"}. OpenAPI lives at /v3/api-docs on port 8080 and requires a bearer token; see API conventions.

3. Run the admin UI

Keep the backend running. In a second terminal opened from the same parent folder, start the admin UI:

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/

The dev server proxies /api/* to the backend on port 8080, so start the backend first. Health checks stay on the separate management port 9090. You can also open the design-system showcase at http://127.0.0.1:5173/design-system.

4. Log in

Open http://127.0.0.1:5173/ and sign in with the fresh-local-database seed account documented in Quick Start. You should land on the admin dashboard; that is the full stack working end to end. This local seed is not a hosted-demo credential. Production-class profiles reject the seed password and require rotation (see Deployment).

Configuration

The backend reads its database and storage settings from environment variables, with sensible local defaults:

Variable	Purpose	Example
`STACKRIVET_DB_VENDOR`	Database dialect	`mysql` (default) / `postgresql`
`STACKRIVET_STORAGE_TYPE`	Asset Service backend	`local` (default) / `s3` / `aliyun_oss`

Common environment variables are documented in Configuration.

Next steps

Project Structure — how the repositories and modules fit together.
Architecture — the modular-monolith design and module boundaries.