# How to Set Up a Development Environment for IPED: A Complete Guide for Digital Forensics Developers

> Set up your IPED development environment. Install Java JDK 11 Maven and Git clone the IPED repository and build the project with mvn clean install. Get started with digital forensics development.

- Repository: [Serviço de Perícias em Informática/IPED](https://github.com/sepinf-inc/IPED)
- Tags: getting-started
- Published: 2026-03-11

---

**Setting up an IPED development environment requires installing Java JDK 11 (Full with JavaFX), Maven 3.6+, and Git, then cloning the sepinf-inc/IPED repository and running `mvn clean install` to build the multi-module Maven project.**

IPED (Integrated Platform for Electronic Discovery) is a Java-based digital forensics suite maintained by sepinf-inc. Whether you are extending the parsing engine or customizing the viewer interface, you need a properly configured development environment to compile the source and run the application from an IDE. This guide walks you through the exact steps to set up a development environment for IPED based on the official source code structure.

## Prerequisites for IPED Development

Before compiling the source code, install the following tools and configure your system environment:

- **Git** – Any recent version is required to clone the repository from GitHub.
- **Maven 3.6+** – Used for build automation and dependency resolution across the multi-module project.
- **Java JDK 11 (Full JDK with JavaFX)** – IPED is compiled for Java 11 and requires JavaFX for the user interface. The **Liberica OpenJDK 11 Full** distribution is recommended because it bundles JavaFX.
- **JAVA_HOME environment variable** – Must point to your JDK 11 installation so Maven and the bootstrap script can locate the compiler and runtime.

Optional but recommended:

- **7-zip or unzip** – Required by the Maven `download-maven-plugin` to unpack external forensic tools during the build process.

## Clone the IPED Repository

Clone the repository from GitHub and navigate to the project root:

```bash
git clone https://github.com/sepinf-inc/IPED.git
cd IPED

```

The repository contains a **multi-module Maven project** defined by the root [`pom.xml`](https://github.com/sepinf-inc/IPED/blob/main/pom.xml). This aggregator manages the following sub-modules:

- `iped-api`
- `iped-utils`
- `iped-parsers`
- `iped-viewers`
- `iped-carvers`
- `iped-geo`
- `iped-engine`
- `iped-app`

The root [`pom.xml`](https://github.com/sepinf-inc/IPED/blob/main/pom.xml) defines common properties, plugin versions, and the build order for the entire suite.

## Build the Project with Maven

Compile all modules and package the release distribution by running:

```bash
mvn clean install

```

This command resolves third-party libraries from Maven Central and compiles each module in the correct dependency order. The final output appears under `target/release/iped-<version>`.

During the build, the **download-maven-plugin** (configured in [`iped-app/pom.xml`](https://github.com/sepinf-inc/IPED/blob/main/iped-app/pom.xml)) automatically pulls external binaries including RegRipper, libyal tools, LibreOffice, and Tesseract, unpacking them into the release folder.

To work on a single module without building the entire project, use the `-pl` flag to limit the build scope:

```bash
mvn -pl iped-parsers clean install

```

This compiles only the specified module and its upstream dependencies, significantly reducing build time during iterative development.

## Run the Application from the Command Line

After a successful build, launch the full graphical interface using the bootstrap class:

```bash
java -cp target/release/iped-4.4.0-SNAPSHOT/iped.jar iped.app.bootstrap.Bootstrap

```

The [`Bootstrap.java`](https://github.com/sepinf-inc/IPED/blob/main/Bootstrap.java) class (located at [`iped-app/src/main/java/iped/app/bootstrap/Bootstrap.java`](https://github.com/sepinf-inc/IPED/blob/main/iped-app/src/main/java/iped/app/bootstrap/Bootstrap.java)) prepares the runtime classpath, configures heap memory settings, and starts the main application.

To launch the headless search UI (report mode), set the `iped.ui.report` system property and use the search application entry point:

```bash
java -Diped.ui.report=true -cp target/release/iped-4.4.0-SNAPSHOT/lib/iped-search-app.jar iped.engine.webapi.Main

```

## Configure Your IDE for IPED Development

Most Java IDEs support Maven project import. Follow these steps to configure IntelliJ IDEA or Eclipse:

1. **Import as Maven project** – Open the cloned `IPED` directory in your IDE and select "Import Maven project". The IDE automatically resolves dependencies from the [`pom.xml`](https://github.com/sepinf-inc/IPED/blob/main/pom.xml) files.
2. **Set the project SDK** – Configure the SDK to point to your Java 11 JDK installation that includes JavaFX.
3. **Create a run configuration** – Set the main class to `iped.app.bootstrap.Bootstrap`. Add the VM option `-Djava.net.useSystemProxies=true` to ensure the application respects system proxy settings when launching from the IDE.

## Update External Tools and Dependencies

The `download-maven-plugin` entries in [`iped-app/pom.xml`](https://github.com/sepinf-inc/IPED/blob/main/iped-app/pom.xml) specify URLs for external forensic binaries. To force a refresh of these tools (for example, after a new Tesseract version is released), activate the `download-tools` profile:

```bash
mvn clean install -Pdownload-tools

```

This profile re-downloads and unpacks all external dependencies defined in the plugin configuration.

## Develop and Test Plugins

IPED supports third-party plugins loaded from the `plugins` directory at runtime. The bootstrap automatically adds this folder to the classpath.

To develop a custom plugin:

1. Create a new Maven module that declares `iped-api` as a compile-time dependency.
2. Implement your plugin classes and package them into a JAR.
3. Copy the resulting JAR into `<release-dir>/plugins`.

The `ConfigurationManager` class (located in [`iped-engine/src/main/java/iped/engine/config/ConfigurationManager.java`](https://github.com/sepinf-inc/IPED/blob/main/iped-engine/src/main/java/iped/engine/config/ConfigurationManager.java)) handles plugin discovery and metadata loading during startup.

## Troubleshoot Common Setup Issues

- **`java.lang.NoClassDefFoundError: javafx/application/Application`** – You are using a JDK distribution that does not include JavaFX. Install a **Full** JDK 11 distribution such as Liberica OpenJDK 11 Full, or manually add the JavaFX SDK to your classpath and update `JAVA_HOME`.

- **Maven fails to download `libyal` or other native tools** – This occurs when the build cannot access the network or the `unzip` utility is missing. Ensure you have internet connectivity or configure Maven to use system proxies. Install `unzip` via your operating system package manager if the `download-maven-plugin` cannot unpack archives.

- **Heap memory errors on large forensic cases** – The default JVM heap size is insufficient for processing large evidence files. Set a larger heap before running Maven or the bootstrap: `export MAVEN_OPTS="-Xmx8g"` or add `-Xmx8g` to your run configuration VM options.

- **Shallow clone missing release tags** – If you cloned with `--depth 1`, Git history is truncated and version tags are missing. Re-clone without the `--depth` flag to ensure all tags are available for stable release builds.

## Summary

- Install **Java JDK 11 Full** (with JavaFX), **Maven 3.6+**, and **Git** before building.
- Clone the `sepinf-inc/IPED` repository and run `mvn clean install` to compile the multi-module project.
- Launch the application via `iped.app.bootstrap.Bootstrap` with the classpath pointing to `iped.jar`.
- Use the `-pl` flag to build individual modules during development.
- Configure your IDE to use Java 11 and import the Maven structure for debugging.
- Place custom plugin JARs in the `plugins` directory to extend functionality.

## Frequently Asked Questions

### What Java version is required for IPED development?

IPED requires **Java 11** specifically, and you must use a **Full JDK** distribution that includes JavaFX (such as Liberica OpenJDK 11 Full). Standard JDK distributions without JavaFX will cause `NoClassDefFoundError` for JavaFX classes when running the graphical interface.

### How do I build only a specific module instead of the entire project?

Use the Maven `-pl` (projects list) flag followed by the module name. For example, `mvn -pl iped-parsers clean install` compiles only the `iped-parsers` module and its required dependencies. This saves significant time when you are modifying code in a single component.

### Why does the build fail when downloading external forensic tools?

The `download-maven-plugin` requires network access to retrieve binaries like Tesseract and LibreOffice, and it needs the `unzip` utility to extract them. Ensure your machine has internet connectivity, configure proxy settings with `-Djava.net.useSystemProxies=true`, and install `unzip` on Linux/macOS systems.

### Can I run IPED in headless mode without the JavaFX GUI?

Yes. Set the system property `-Diped.ui.report=true` and launch the search application using `iped.engine.webapi.Main` with `iped-search-app.jar` on the classpath. This starts the headless search interface without requiring JavaFX rendering components.