# How to Set Up the Stirling-PDF Local Development Environment with Gradle and npm

> Easily set up the Stirling-PDF local development environment. Follow simple steps using Gradle and npm to launch the backend and frontend servers for seamless development.

- Repository: [Stirling Tools/Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF)
- Tags: getting-started
- Published: 2026-03-01

---

**To set up the Stirling-PDF local development environment with Gradle and npm, clone the repository, execute `./gradlew bootRun` to launch the Spring Boot backend on `localhost:8080`, then run `npm ci` and `npm run dev` inside the `frontend` directory to start the Vite React development server on `localhost:5173`.**

Stirling-PDF combines a **Spring Boot** Java backend with a **Vite/React** JavaScript frontend. Setting up the local development environment requires configuring both the Gradle wrapper for backend compilation and npm for frontend dependency management, enabling you to modify and test the full application stack locally.

## Prerequisites

Before starting, ensure your system meets the following requirements:

- **Java JDK 17+** – Required to compile the Spring Boot backend.
- **Node.js ≥ 20** and **npm** – Required for frontend tooling and package management.
- **Git** – To clone the repository.
- **Docker** (optional) – Needed for full-stack integration testing with external binaries like LibreOffice and qpdf.
- **Calibre CLI** (optional) – Required only if testing e-book to PDF conversion features.

The project includes a Gradle wrapper, so you do not need to install Gradle globally. The wrapper automatically downloads version `9.3.1` as specified in `gradle/wrapper/gradle-wrapper.properties`.

## Clone the Repository

Start by cloning the official repository and entering the project directory:

```bash
git clone https://github.com/Stirling-Tools/Stirling-PDF.git
cd Stirling-PDF

```

## Backend Setup with Gradle

The backend build logic is defined in `build.gradle` and managed through the Gradle wrapper script (`gradlew`).

### Build the Project

Compile the Java source and package the application:

```bash
./gradlew clean build

```

This command downloads the exact Gradle version (`9.3.1`) defined in `gradle/wrapper/gradle-wrapper.properties`, installs dependencies, and produces the executable JAR.

### Run the Backend Locally

Start the Spring Boot application in development mode:

```bash
./gradlew bootRun

```

The backend service starts on **`http://localhost:8080`**. By default, this runs with additional security features disabled to streamline development.

### Enable Security Features

To test authentication, audit logs, and other security features locally, set the environment variable before launching:

```bash
export DISABLE_ADDITIONAL_FEATURES=false
./gradlew bootRun

```

This configuration is documented in the [`devGuide/DeveloperGuide.md`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md) under the environment variables section.

## Frontend Setup with npm

The frontend source code resides in the `frontend` directory and uses Vite as the build tool.

### Install Dependencies

Navigate to the frontend directory and install exact dependency versions:

```bash
cd frontend
npm ci

```

The `npm ci` command reads [`frontend/package.json`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/frontend/package.json) and [`package-lock.json`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/package-lock.json) to ensure reproducible builds across development machines.

### Start the Development Server

Launch the Vite development server:

```bash
npm run dev

```

The server starts on **`http://localhost:5173`** and automatically proxies API requests to the backend at `localhost:8080` via the proxy configuration defined in [`package.json`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/package.json).

### Available npm Scripts

The [`frontend/package.json`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/frontend/package.json) defines several useful scripts for development:

- **`npm run dev`** – Starts the Vite development server with hot module replacement.
- **`npm run build`** – Creates an optimized production bundle for deployment.
- **`npm run lint`** – Runs ESLint and circular dependency checks.
- **`npm run test`** – Executes the Vitest unit test suite.
- **`npm run e2e`** – Runs Playwright end-to-end tests against the running application.

## Full-Stack Development Workflow

To work on both backend and frontend code simultaneously:

1. **Start the backend** in a terminal window:

   ```bash
   ./gradlew bootRun
   ```

2. **Start the frontend** in a second terminal:

   ```bash
   cd frontend
   npm run dev
   ```

3. Open **`http://localhost:5173`** in your browser. The Vite server handles UI rendering and proxies all `/api/*` requests to the Gradle backend, providing a seamless development experience.

## Docker-Based Testing (Optional)

To verify functionality that depends on external binaries (LibreOffice, qpdf, OCR tools), build and run the full Docker image:

```bash
export DISABLE_ADDITIONAL_FEATURES=true
./gradlew clean build
docker build -t stirlingtools/stirling-pdf:dev -f Dockerfile .
docker run -p 8080:8080 stirlingtools/stirling-pdf:dev

```

Alternatively, run the comprehensive test suite using the provided script:

```bash
./test.sh

```

This script builds all Docker images and executes Cucumber integration tests as defined in the developer guide.

## Summary

- **Stirling-PDF** requires both **Gradle** (via wrapper) and **npm** to build the full application locally.
- The **Gradle wrapper** (`./gradlew`) handles Java backend compilation and runs on port **8080**.
- The **npm/Vite** frontend toolchain installs via `npm ci` and serves the UI on port **5173** with automatic API proxying.
- Set **`DISABLE_ADDITIONAL_FEATURES=false`** to enable security testing during local development.
- Use **[`./test.sh`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/./test.sh)** for full Docker-based integration testing when validating external tool dependencies.

## Frequently Asked Questions

### What version of Gradle does Stirling-PDF use?

The project uses **Gradle 9.3.1**, pinned in `gradle/wrapper/gradle-wrapper.properties`. You do not need a local Gradle installation; the `./gradlew` wrapper script automatically downloads and caches this version on first run.

### Should I use `npm install` or `npm ci` for the frontend?

Use **`npm ci`** when setting up the development environment. This command installs exact versions from [`package-lock.json`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/package-lock.json), ensuring consistency with the repository's tested dependency tree. Use `npm install` only when intentionally updating dependencies.

### How do I enable user authentication during local development?

Set the environment variable **`DISABLE_ADDITIONAL_FEATURES=false`** before starting the backend with `./gradlew bootRun`. By default, this variable is `true` in development mode, which disables login, audit logs, and other security features to simplify testing.

### Which ports are used during local development?

The **backend** runs on port **8080** (configurable via Spring Boot properties), and the **frontend** development server runs on port **5173**. The frontend proxy configuration in [`frontend/package.json`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/frontend/package.json) automatically forwards API calls from the browser to the backend, preventing cross-origin issues.