NiFi Custom NAR Bundle

A Maven multi-module project for building custom Apache NiFi processor NARs targeting Apache NiFi 2.4.0.

Version Matrix

Component	Version	Notes
Java JDK	21	maven.compiler.release=21
NiFi runtime	2.4.0	Target NiFi version
NiFi API (standalone)	2.2.0	org.apache.nifi:nifi-api — scope provided
NiFi NAR Maven Plugin	2.1.0	Enables nar packaging
Maven	3.9+	Any 3.9.x or later
Maven Compiler Plugin	3.13.0	Supports <release>21</release>
JUnit Jupiter	5.10.2	Unit testing with NiFi TestRunner

Prerequisites

1. JDK 21 — Install Eclipse Temurin 21 via Homebrew:

   brew install --cask temurin@21

2. Maven 3.9+ — Install via Homebrew:

   brew install maven

3. Podman — Required for local development containers:

   brew install podman
   podman machine init
   podman machine start

4. Set JAVA_HOME — Add to ~/.zshrc:

   export JAVA_HOME=$(/usr/libexec/java_home -v 21)

   Then reload: source ~/.zshrc

5. Verify:

   java -version      # should show 21.x
   mvn -version       # should show 3.9.x+ and Java 21
   podman --version   # should show 4.x or 5.x

Quick Start

./dev.sh build          # Build the NAR
./dev.sh deploy         # Stage NAR for NiFi
./dev.sh up             # Start NiFi + MSSQL containers
# Wait 60-90s, then open https://localhost:8443/nifi

Build

From the project root:

# Compile, test, and package the NAR
mvn clean package

# Skip tests during build
mvn clean package -DskipTests

# Resolve dependencies only
mvn dependency:resolve

The NAR file will be produced at:

nifi-custom-processors-nar/target/nifi-custom-processors-nar-1.0.0-SNAPSHOT.nar

Local Development (Podman)

A dev.sh helper script manages local NiFi and MSSQL containers via Podman for development, testing, and debugging.

Containers

Service	Image	Port	Credentials
NiFi 2.4.0	apache/nifi:2.4.0	8443 (HTTPS UI), 8000 (JVM debug)	admin / xK9mP2qL5vN8wR4t
MSSQL (Azure SQL Edge)	mcr.microsoft.com/azure-sql-edge:latest	1433	sa / Dev0nly!Pass99

NiFi processors can reach MSSQL at mssql-dev:1433 by container hostname. From the host, connect to localhost:1433.

dev.sh Commands

Command	Description
./dev.sh build	Build the NAR (mvn clean package -DskipTests)
./dev.sh deploy	Copy NAR to extensions/ staging directory
./dev.sh up	Start all containers (NiFi + MSSQL)
./dev.sh down	Stop all containers, remove volumes and staged NARs (fresh each time)
./dev.sh restart	Restart NiFi container
./dev.sh reload	Build + deploy + restart NiFi (full dev cycle)
./dev.sh logs	Tail all container logs (logs nifi or logs mssql for one service)
./dev.sh status	Show container status and NiFi UI readiness

Development Workflow

./dev.sh build          # 1. Build the NAR
./dev.sh deploy         # 2. Stage NAR for NiFi
./dev.sh up             # 3. Start NiFi + MSSQL
# Open https://localhost:8443/nifi (accept self-signed cert warning)
# Edit code...
./dev.sh reload         # 4. Rebuild + redeploy + restart NiFi
./dev.sh down           # 5. Tear down (removes all volumes for a fresh start)

JVM Remote Debugging

JVM debug is enabled by default on port 8000. Attach your IDE debugger to localhost:8000.

JDBC Driver

The MSSQL JDBC driver (mssql-jdbc-13.4.0.jre11.jar) is in the drivers/ directory and mounted into the NiFi container at /opt/nifi/nifi-current/drivers/. Use this path when configuring NiFi's DBCPConnectionPool controller service.

Adding New Processors

1. Create a new Java class in nifi-custom-processors/src/main/java/com/custom/nifi/processors/ that extends AbstractProcessor.
2. Register it by adding the fully qualified class name to nifi-custom-processors/src/main/resources/META-INF/services/org.apache.nifi.processor.Processor.
3. Write a test in nifi-custom-processors/src/test/java/com/custom/nifi/processors/.
4. Rebuild: mvn clean package.

Project Structure

nifi-custom-nar-bundle/
├── pom.xml                          # Parent POM (packaging: pom)
├── dev.sh                           # Development helper script
├── docker/
│   ├── compose.yaml                 # NiFi 2.4.0 container
│   └── compose.mssql.yaml           # MSSQL (Azure SQL Edge) container
├── extensions/                      # Staged NAR files (mounted into NiFi)
├── drivers/                         # JDBC drivers (mounted into NiFi)
├── nifi-custom-processors/          # Processor code (packaging: jar)
│   ├── pom.xml
│   └── src/
│       ├── main/java/...            # Processor implementations
│       ├── main/resources/META-INF/ # Service registration
│       └── test/java/...            # Unit tests
└── nifi-custom-processors-nar/      # NAR packaging (packaging: nar)
    └── pom.xml

Troubleshooting

Build fails with "invalid source/target release" Ensure JAVA_HOME points to JDK 21 and Maven uses it: mvn -version should show Java 21.

ClassNotFoundException at NiFi runtime Verify the processor's fully qualified name is listed in META-INF/services/org.apache.nifi.processor.Processor.

NAR not detected by NiFi Run ./dev.sh logs nifi and look for NAR loading messages. The NAR must be in extensions/ before starting the container. If already running, use ./dev.sh reload.

Dependency conflicts The nifi-api must remain scope provided. If you add libraries that NiFi already bundles, mark them provided to avoid classloader conflicts.

Maven uses wrong Java version Run export JAVA_HOME=$(/usr/libexec/java_home -v 21) before building, or add it permanently to ~/.zshrc.

MSSQL container crashes (Apple Silicon) The standard mcr.microsoft.com/mssql/server image segfaults on ARM64. This project uses Azure SQL Edge (mcr.microsoft.com/azure-sql-edge) which is ARM64-native.

NiFi container keeps restarting Check ./dev.sh logs nifi for errors. Common causes: port 8443 already in use, or volume mount permissions.