Skip to main content
This guide will walk you through setting up a complete development environment for Halo. You’ll configure both the backend and frontend development servers.

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

​
Required software

  • Java 21: JDK 21 or later is required for building and running the backend
  • Node.js: Latest LTS version (for frontend development)
  • pnpm 10: Package manager for frontend dependencies
  • Git: Version control system
  • Docker (optional): For running databases and testing

​
Verify installations

Check that you have the correct versions installed: 
java -version
# Should show Java 21 or later
The project uses Gradle Wrapper, so you don’t need to install Gradle separately. The wrapper will automatically download Gradle 9.3.0.

​
Clone the repository

Clone the Halo repository with all submodules:
1

Fork and clone the repository

First, fork the repository on GitHub, then clone your fork:
git clone https://github.com/{YOUR_USERNAME}/halo
cd halo
2

Initialize submodules

Halo uses Git submodules. Initialize and update them:
git submodule init
git submodule update
3

Add upstream remote

Add the original repository as an upstream remote:
git remote add upstream https://github.com/halo-dev/halo.git

​
Backend setup

Set up the Spring Boot backend application.
1

Verify Java version

The project requires Java 21. The build configuration enforces this:
application/build.gradle
tasks.withType(JavaCompile).configureEach {
    options.release = 21
    options.encoding = 'UTF-8'
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}
Make sure your JAVA_HOME points to Java 21.
2

Build the project

Use the Gradle wrapper to build the entire project:
./gradlew clean build -x check
This command:
  • Cleans previous build artifacts
  • Builds all modules
  • Skips tests and checks for faster initial setup
The first build may take several minutes as Gradle downloads dependencies.
3

Run the backend server

Start the development server:
./gradlew bootRun
The backend will start on http://localhost:8090.Alternatively, you can run with specific profiles:
./gradlew bootRun --args='--spring.profiles.active=dev'
The backend requires a database to run. By default, Halo uses an embedded H2 database for development. For production-like testing, configure PostgreSQL or MySQL.

​
Frontend setup

Set up the Vue.js console application.
1

Install pnpm globally

If you haven’t already, install pnpm globally:
npm install -g pnpm@10
2

Navigate to the UI directory

cd ui
3

Install dependencies

Install all frontend dependencies:
pnpm install
This command installs dependencies for the main application and all packages in the workspace.
4

Build shared packages

Before running the dev server, build the shared packages:
pnpm build:packages
This builds internal packages like @halo-dev/api-client, @halo-dev/components, and others that the console depends on.
5

Start the development server

Run the frontend development server:
pnpm dev
This starts two development servers:
  • Console: http://localhost:5173 (main admin interface)
  • User Center: http://localhost:5174 (user-facing interface)
You can also run them individually:
pnpm dev:console

​
Running both servers

For full-stack development, you need both backend and frontend running:
1

Terminal 1: Backend

In the root directory:
./gradlew bootRun
Wait until you see the Spring Boot startup message.
2

Terminal 2: Frontend

In the ui directory:
pnpm dev
3

Access the application

Open your browser:
  • Frontend console: http://localhost:5173
  • Backend API: http://localhost:8090
  • Console API docs: http://localhost:8090/swagger-ui.html
The frontend development server proxies API requests to the backend server automatically through Vite’s proxy configuration.

​
Development tips

​
Hot reload

Both servers support hot reload:
  • Backend: Spring Boot DevTools enables automatic restart
  • Frontend: Vite provides instant hot module replacement (HMR)

​
Running tests

./gradlew test

​
Code formatting

Ensure your code is properly formatted before committing: 
./gradlew checkstyleMain

​
Type checking

For TypeScript type checking in the frontend: 
cd ui
pnpm typecheck

​
Generate API client

After modifying backend APIs, regenerate the frontend API client: 
cd ui
pnpm api-client:gen

​
Building for production

When you’re ready to create production builds:
1

Build backend

./gradlew build
This creates an executable JAR file in application/build/libs/halo.jar.
2

Build frontend

cd ui
pnpm build
This creates optimized production bundles in ui/build/dist/.
The full production build automatically includes the frontend assets in the backend JAR file through the copyUiDist Gradle task.

​
Troubleshooting

​
Gradle build fails

If the Gradle build fails:
  1. Ensure Java 21 is installed and JAVA_HOME is set correctly
  2. Clear Gradle cache: ./gradlew clean --refresh-dependencies
  3. Check for permission issues on gradlew file

​
Frontend dependencies fail

If dependency installation fails:
  1. Clear pnpm cache: pnpm store prune
  2. Delete node_modules and pnpm-lock.yaml, then reinstall
  3. Ensure you’re using pnpm 10.x

​
Port conflicts

If ports 8090, 5173, or 5174 are already in use:
  • Backend: Add --args='--server.port=8091' to bootRun
  • Frontend: Vite will automatically use the next available port

​
Database connection issues

For database-related errors:
  1. Check database configuration in application/src/main/resources/application.yaml
  2. Ensure the database service is running
  3. Verify connection credentials

​
Next steps

Extension system

Learn about Halo’s extension framework

Plugin development

Build your first Halo plugin

Theme development

Create a custom theme for Halo

API reference

Explore the API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us