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

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:

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. 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 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:

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) 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:

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:

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

The Bootstrap.java class (located at 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:

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 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 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:

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) 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}