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 backend and its OpenAPI explorer running fast, the Quick Start is shorter.

Prerequisites

Tool	Version	For
JDK	21	Backend (the default and only supported major)
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

mvn install -DskipTests=true          # build all 16 modules once
mvn -pl stackrivet-app spring-boot:run # run the Spring Boot app

The API comes up on port 8080. Open the OpenAPI explorer to confirm:

open http://127.0.0.1:8080/swagger-ui.html

(On Linux or Windows, visit the URL in your browser.)

3. Run the admin UI

In the stackrivet-admin-ui repository:

cd stackrivet-admin-ui
pnpm install
pnpm dev          # http://127.0.0.1:5173/

The dev server proxies /api/* and /actuator/* to the backend on port 8080, so start the backend first. You can also open the design-system showcase at http://127.0.0.1:5173/design-system.

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.