> ## Documentation Index
> Fetch the complete documentation index at: https://docs.drpn.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up Darpan independently

> Clone the Darpan repositories and start a local development stack.

Setting up a local Darpan stack is more involved than a typical frontend project. JDK 21 is a hard requirement, Spark needs specific JVM flags before the backend will start, and the backend is a Moqui framework with Darpan components nested inside. This tutorial walks through each step. If you want the one-command path, the `darpan` CLI at the top of this page handles all of it.

<Tip>
  **Fastest path (macOS, Homebrew):** if you want a running stack without the manual steps, install the `darpan` CLI and let it do all of the steps below for you:

  ```bash theme={null}
  brew tap drpn-ai/tap
  brew install darpan
  darpan doctor   # check prerequisites (JDK 21, Node 20+, ports)
  darpan up       # clone, load, and start the stack
  ```

  Follow the manual steps below when you want full control over the workspace, are not on macOS/Homebrew, or are debugging the setup itself.
</Tip>

The local stack runs:

| Service        | Default URL                      | Purpose                              |
| -------------- | -------------------------------- | ------------------------------------ |
| Darpan UI      | `http://localhost:5173`          | Vue app used in the browser.         |
| Darpan backend | `http://localhost:8080`          | Moqui backend and JSON-RPC services. |
| JSON-RPC       | `http://localhost:8080/rpc/json` | API endpoint used by the UI.         |

## Before you start

Install these first:

| Tool       | Version            | Check           |
| ---------- | ------------------ | --------------- |
| Git        | Current stable     | `git --version` |
| Java (JDK) | **21**             | `java -version` |
| Node.js    | 20 or newer        | `node -v`       |
| npm        | Comes with Node.js | `npm -v`        |

<Warning>
  Darpan runs on **Moqui 4 + Spark 3.5 + Drools-MVEL 2.5**, which require **JDK 21**. The backend will not start on Java 17. Install Temurin 21 and make it the active JDK before running any Gradle command:

  ```bash theme={null}
  # macOS (Homebrew)
  brew install --cask temurin@21
  export JAVA_HOME=$(/usr/libexec/java_home -v 21)
  java -version   # must report 21.x
  ```
</Warning>

You also need GitHub access to the `drpn-ai` Darpan repositories. If a clone command asks for authentication or returns `Repository not found`, confirm that your GitHub account has access before changing any commands.

<Tip>
  Keep the backend and UI as sibling folders. The UI dev-stack helper expects that layout by default.
</Tip>

## Folder layout

This guide creates this layout:

```text theme={null}
darpan-local/
  darpan-backend/
    runtime/component/darpan/
    runtime/component/darpan-hotwax/
    runtime/component/moqui-sftp/
    runtime/component/netsuite-darpan/
    runtime/component/shopify-darpan/
  darpan-ui/
```

`darpan-backend` is a Moqui framework checkout. The Darpan backend code lives inside `darpan-backend/runtime/component/**`.

<Note>
  Moqui 4 uses the **embedded Bitronix** transaction manager. The old `moqui-atomikos` component is retired and is no longer cloned or built.
</Note>

## Set the JDK 21 runtime flags

The backend JVM needs a set of `--add-opens` flags (the canonical Spark 3.5 / JDK 21 list) plus a couple of agent and native-access flags. Spark SQL fails at startup without them. Export them in the shell you will use for every backend command (`load`, `run`, and `npm run dev:stack`):

```bash theme={null}
export JAVA_TOOL_OPTIONS="\
--add-opens=java.base/java.lang=ALL-UNNAMED \
--add-opens=java.base/java.lang.invoke=ALL-UNNAMED \
--add-opens=java.base/java.lang.reflect=ALL-UNNAMED \
--add-opens=java.base/java.io=ALL-UNNAMED \
--add-opens=java.base/java.net=ALL-UNNAMED \
--add-opens=java.base/java.nio=ALL-UNNAMED \
--add-opens=java.base/java.util=ALL-UNNAMED \
--add-opens=java.base/java.util.concurrent=ALL-UNNAMED \
--add-opens=java.base/java.util.concurrent.atomic=ALL-UNNAMED \
--add-opens=java.base/sun.nio.ch=ALL-UNNAMED \
--add-opens=java.base/sun.nio.cs=ALL-UNNAMED \
--add-opens=java.base/sun.security.action=ALL-UNNAMED \
--add-opens=java.base/sun.util.calendar=ALL-UNNAMED \
--add-opens=java.security.jgss/sun.security.krb5=ALL-UNNAMED \
-XX:+EnableDynamicAgentLoading \
--enable-native-access=ALL-UNNAMED"
```

<Tip>
  If you clone the Darpan workspace wrapper instead of setting up from scratch, the wrapper's `./dev-stack.sh` exports these flags for you and preflights JDK 21. See [the wrapper README](https://github.com/drpn-ai/darpan) for the fast path. This standalone guide sets them manually because `gradle run` does not set them on its own.
</Tip>

## Clone the backend

Create a parent folder and clone Moqui framework as `darpan-backend`:

```bash theme={null}
mkdir -p darpan-local
cd darpan-local
git clone --branch master https://github.com/moqui/moqui-framework.git darpan-backend
cd darpan-backend
```

Download the Moqui runtime folder:

```bash theme={null}
./gradlew getRuntime
```

The first Gradle command downloads the Gradle wrapper distribution and Moqui runtime. Let it finish before cloning the Darpan components.

## Clone the backend components

Clone the required runtime components into `runtime/component`:

```bash theme={null}
cd runtime/component
git clone --branch master https://github.com/moqui/moqui-sftp.git moqui-sftp
git clone --branch main https://github.com/drpn-ai/darpan.git darpan
git clone --branch main https://github.com/drpn-ai/shopify-darpan.git shopify-darpan
git clone --branch main https://github.com/drpn-ai/netsuite-darpan.git netsuite-darpan
git clone --branch main https://github.com/drpn-ai/darpan-hotwax.git darpan-hotwax
cd ../..
```

`moqui-sftp` is needed by the Darpan component build and test classpath. The four Darpan components provide the core backend, Shopify integration, NetSuite integration, and HotWax integration.

## Load local setup data

From `darpan-backend`, load the framework and Darpan setup data:

```bash theme={null}
./gradlew load
```

`load` runs with `types=all`, so it loads every data file in dependency-safe order, including the framework seed data and Darpan's custom `darpan-seed-initial` (type definitions) and `darpan-seed` (setup records) files. The first load can take several minutes because Gradle also resolves backend dependencies and builds the components.

<Warning>
  Run data-load commands only when the backend server is stopped. If a load fails with a Bitronix or H2 lock error, stop the running backend process and rerun the load.
</Warning>

<Note>
  `./gradlew loadDarpanUpgradeData` is a different command. It loads only the current release's `upgrade-data.xml` for existing environments and is **not** a substitute for `./gradlew load` on a fresh setup.
</Note>

## Clone the UI

Go back to the parent folder and clone the Darpan UI:

```bash theme={null}
cd ..
git clone --branch main https://github.com/drpn-ai/darpan-ui.git darpan-ui
cd darpan-ui
npm install
```

Local development does not require a `.env` file. When no API URL is configured, Vite proxies `/rpc/json` to `http://localhost:8080`.

## Start the stack

Start backend and frontend together from `darpan-ui`:

```bash theme={null}
npm run dev:stack
```

Keep this terminal open. The dev-stack helper starts both processes and stops them when the command exits.

<Warning>
  The UI's `npm run dev:stack` helper starts the backend with `./gradlew run` but does **not** set `JAVA_TOOL_OPTIONS` for you. Export the JDK 21 runtime flags (see [Set the JDK 21 runtime flags](#set-the-jdk-21-runtime-flags)) in the same shell first, or Spark reconciliation will fail even though the backend appears to boot.
</Warning>

The helper uses:

| Setting         | Default                     |
| --------------- | --------------------------- |
| Backend folder  | `../darpan-backend`         |
| Backend command | `./gradlew --no-daemon run` |
| Backend port    | `8080`                      |
| Frontend port   | `5173`                      |

If your backend folder is somewhere else, pass the path explicitly:

```bash theme={null}
DARPAN_BACKEND_DIR=/absolute/path/to/darpan-backend npm run dev:stack
```

If port `8080` or `5173` is already in use, the helper tries to stop the existing listener before starting the new stack.

## Sign in locally

Open the UI:

```text theme={null}
http://localhost:5173/login
```

If no local admin user exists yet, open the backend login page:

```text theme={null}
http://localhost:8080/Login
```

Moqui shows an initial administrator setup form when the database has no user accounts. Create the local admin user there, then return to `http://localhost:5173/login` and sign in with the same username and password.

Do not use local development credentials in hosted or shared environments.

## Confirm the setup

After sign-in, confirm these checks:

* The Darpan UI opens at `http://localhost:5173`.
* The backend login page opens at `http://localhost:8080/Login`.
* The app can sign in without a `No active authenticated session` loop.
* **Ask Darpan** opens with `Cmd/Ctrl+K` or the floating **Ask Darpan** button.
* **Open User Settings** loads from the local backend.
* **Open Runs Settings** or **Create Reconciliation Flow** loads without API errors.

If the UI opens before the backend finishes booting, wait a minute and refresh. Moqui startup takes longer on the first run.

## Daily startup

After the first setup, the normal development startup is:

```bash theme={null}
cd darpan-local/darpan-ui
npm run dev:stack
```

You do not need to rerun `./gradlew load` every day. Rerun it when seed data changes, the local database is missing, or a backend change explicitly requires a reload. Keep `JAVA_TOOL_OPTIONS` exported in the shell each session.

## Development checks

Run checks from the repository that owns the change.

Frontend:

```bash theme={null}
cd darpan-local/darpan-ui
npm run check
```

Backend:

```bash theme={null}
cd darpan-local/darpan-backend
./gradlew :runtime:component:darpan:compileGroovy
./gradlew :runtime:component:darpan:test
```

Use focused tests while working, then run broader checks before handing off or opening a pull request.

## Common fixes

If setup fails — for example a Spark startup error, a JDK version error, a clone failure, or a database lock — see [Local development setup](/troubleshooting/local-dev-setup) for recovery steps.

## Clean rebuild for a throwaway local database

Only use this when you are comfortable deleting the local development database:

```bash theme={null}
cd darpan-local/darpan-backend
./gradlew cleanDb
./gradlew load
```

Then restart:

```bash theme={null}
cd ../darpan-ui
npm run dev:stack
```