When a custom Apache NiFi distribution is worth building
Build a custom Apache NiFi distribution when a flow depends on an optional bundle, such as graph, media or gRPC support, that the convenience binary does not include and every node must run the same bundle set from one build. The nifi-assembly module in the apache/nifi repository is where that set is chosen. Maven profiles select which optional bundles are packaged, and the output is a distribution directory you can archive, checksum and deploy in place of the official binary. Use this route when the bundle list stays stable across development, test and production, when you must reproduce the same artifact later for audit or rollback, or when the target network cannot reach public repositories at install time. If a bundle is needed in only one environment or changes often, adding it at runtime is usually the lighter option.
Apache NiFi is licensed under the Apache License 2.0 (SPDX identifier Apache-2.0), and the project offers no paid edition. Building your own distribution therefore carries no license fee. The cost is engineering time: choosing and testing the bundle set, building and signing the artifact in your pipeline, running regression tests on each new build, and rebuilding for each NiFi release you adopt. The rebuild and retest effort recurs at every upgrade, because the assembly follows the NiFi version you build against. Ask any partner quoting this work to separate one-time build setup from recurring rebuild and retest effort, and to state the NiFi release the quote covers. Check the NiFi download page for current release status before you fix a version.
The decision comes down to change control. A custom build gives you one artifact with a known set of NARs, which suits regulated environments and isolated networks, but each new bundle or NiFi version means a new build and a new test cycle. Runtime loading avoids rebuilds but spreads the bundle set across nodes and adds a startup dependency you must monitor. Confirm with your own change board which model your audit trail requires before the build starts. Then verify that every bundle you need exists for the NiFi line you plan to run, since 1.x and 2.x differ, and that its dependencies can be resolved in the environment where the build will run.
Choosing between the convenience binary, a custom build and runtime NAR installs
This table compares the three ways to get NiFi bundles that are not in the default binary: the convenience binary, a custom distribution built from the nifi-assembly module, and NARs installed at runtime. Read each row against your own team's build capacity and change control, because the ownership and upgrade burden differ more than the initial setup does.
| Decision point | Convenience binary | Custom distribution build | Runtime NAR installs |
|---|---|---|---|
| When it fits | Standard flows that use only the bundles shipped in the official binary | Several optional bundles must ship in one artifact for every node, such as graph, media or gRPC support | A small number of extra NARs is needed on a running instance without a full rebuild |
| Who owns the build artifact | The Apache NiFi project publishes it; your team only verifies the download | Your team or partner owns the Maven profiles, the output archive and its verification | Your team owns the NAR files, their source and the autoload or provider configuration |
| How upgrades are handled | Replace the install with the new release and review the migration notes | Rebase the profile configuration onto each new NiFi version and rebuild before testing | Check each NAR against the new NiFi version, since extensions may need rebuilding |
| Air-gapped or regulated fit | Easiest to verify, but may lack the bundles the flows need | Strongest control over contents, with a larger build and evidence burden to maintain | Flexible on isolated networks, but harder to show exactly which code ran on each node |
| Main trade-off | Lowest ownership cost, with a limit on which components are available | Full control of contents, paid for with ongoing build maintenance across upgrades | Fast change with less audit visibility, so version control of each NAR is essential |
Build sequence for a custom NiFi distribution
The sequence turns a pinned NiFi source tree into a verified distribution that contains only the optional bundles your flows need. Each step leaves a record you can check before the build moves on.
Pin the source to a release tag
The engineer responsible for the build checks out the apache/nifi repository at a specific release tag rather than a moving branch, so the same inputs produce the same distribution later. Record the tag name, the commit hash it resolves to, and the version declared in the root pom. Confirm the tag matches the NiFi release line you intend to run, whether that is 2.x or a supported 1.x line, and check the migration guidance before choosing a 1.x tag for new work. The step is done when the tag, commit hash and project version are written into the build record.
Confirm the Java 21 build toolchain
Install a JDK that meets the Java 21 minimum listed in the NiFi administration guide and set JAVA_HOME so Maven uses it. Verify the Maven version your team uses against the build instructions in the source tree, then run a version check for both tools on the build host. Also confirm that Python 3.10, 3.11 or 3.12 is present if the bundles you plan to include depend on Python-based processors, which the administration guide describes as a beta feature. The step is done when the version output for Java, Maven and Python is captured in the build record.
Select the Maven profiles for required bundles
Review the nifi-assembly module and its profiles to map each optional bundle you need, such as graph, media or gRPC support, to the profile that includes it. Keep the list short, because every added bundle increases the artifact size, the attack surface and the number of components to test after each upgrade. Write the selected profile names and the business reason for each into the build record, and ask the project's current documentation or the repository to confirm the profile names for the tag you pinned. The step is done when the profile list is approved by the flow owner and the security reviewer.
Run the Maven build with the selected profiles
Run the Maven build for the nifi-assembly module with the chosen profiles on a clean build host or container, using the offline or mirrored repository policy your organization requires. Capture the full command line, the Maven settings file in use, and the build log. Treat any failed test or dependency resolution as a stop condition, and resolve it by changing the pinned inputs rather than skipping tests. The step is done when the build finishes without errors and the output archive is written to the target directory.
Record checksums of the artifact
Generate a SHA-256 checksum for the assembled archive and store it alongside the source tag, commit hash, profile list and build log in your artifact repository. Keep the same record format for every build so that a later reviewer can match a deployed file to the exact inputs that produced it. Confirm that the checksum recorded at build time is the one your deployment pipeline verifies before installation. The step is done when the checksum and the metadata are stored together and can be retrieved by version.
Verify the distribution starts
Extract the archive on a test host, start NiFi with the configuration your environment uses, and confirm the startup log reports that the application has started without errors. Check that the UI or API responds on the address you configured, and that the bundles you selected load without missing-class or conflicting-NAR messages in the log. Stop the instance and keep the log as evidence. The step is done when a clean start is recorded against the checksum of the artifact being tested.
Confirm expected components are listed
Open the component list in the running instance, or query the equivalent API endpoint, and confirm that each processor, controller service and other component from the selected bundles appears. Compare the result with the expected list drawn from the profile selection in step three, and investigate any missing or unexpected component before release. Save the exported list with the build record so that future upgrades can be compared against it. The step is done when the component list matches the approved profile list and is stored with the checksum.
Adjusting the build for graph, media and gRPC bundles
Graph support adds processors that read from or write to graph databases. In a custom build, the work is mostly about deciding which graph processors belong in the NARs you ship and making sure their client libraries resolve correctly. The processor code is only part of the artifact. Each graph client brings transitive dependencies, and those must be compatible with the Java 21 runtime and with the libraries NiFi already provides.
- Target database choice: Include only the graph bundle for the database your flows write to, so the assembly does not carry clients you never use.
- Driver versions: Confirm the client driver version against the database server version your team runs, since compatibility is set by the database vendor.
- Shared dependencies: Check for conflicts with Jackson, Netty or logging libraries that NiFi already ships, because duplicate versions cause hard-to-trace class loading errors.
- Licensing: Review the license of each transitive dependency before the distribution goes to internal teams or air-gapped sites.
- Functional tests: Run a flow that reads and writes sample nodes after the build, not just a startup check.
Confirm the exact graph bundle name and its Maven profile flag in the nifi-assembly configuration of the apache/nifi repository for the release you are building, because bundle names and flags change between releases.
Media support covers processors that inspect, transform or extract metadata from audio, video and image files. These bundles often depend on native libraries and codecs that the convenience binary does not include, so the build has to account for platform-specific components. Media processing is also memory and CPU intensive, which affects the JVM and repository plan before the build starts.
- Native components: Identify whether the bundle calls external binaries or native libraries, and package the right builds for each operating system and architecture in your fleet.
- Codec licensing: Confirm which codecs are included and whether their patent or redistribution terms need legal review before you ship them.
- Resource profile: Size heap and temporary storage for large files, because media payloads can dominate content repository use.
- Offline delivery: Bundle every native file with the NARs, since a restricted network cannot download them at startup.
- Representative fixtures: Verify the build with sample media in every format your sources send, including the edge cases such as truncated or unusual files.
Confirm the media bundle name, the list of native dependencies and the profile flag in the repository for your chosen release before you finalize the artifact set.
gRPC support adds processors and services that send and receive gRPC messages. The build brings in gRPC and Protocol Buffers runtime libraries, along with TLS handling that has to match how your NiFi instance is secured. If your team generates code from its own .proto definitions, that generation step belongs in the build and must be repeatable from source control.
- Protobuf alignment: Keep the protobuf and gRPC library versions the bundle declares, and check that they do not clash with versions loaded by another NAR.
- Generated code: Pin the protoc version used to generate classes from your .proto files and record it in the build configuration.
- TLS integration: Confirm the processor accepts the keystore and truststore formats your NiFi security configuration uses.
- Network path: Document the ports and HTTP/2 path through any load balancer or proxy placed in front of the gRPC endpoint.
- Contract tests: Run round-trip tests against a server stub built from the same proto files that production uses.
Confirm the gRPC bundle name, the profile flag and the library versions declared in the repository for your release, since the project updates these dependencies over time.
Keeping the custom build working across NiFi upgrades
A custom distribution is only as current as its last rebase. The six concerns below run in parallel: the release line you track, the migration changes you review, the flows you retest, the artifacts you rebuild, the 1.x to 2.x move, and the Registry deprecation that will eventually affect the tooling around the build. Plan them together so one upgrade does not stall the others.
Rebasing onto new release tags
Each upgrade starts by moving your fork or build configuration onto the new release tag of the apache/nifi repository, then re-applying your Maven profile changes and added bundle versions. Keep the list of profile and dependency edits in version control as a short patch set so the rebase is reviewable. Check that the optional bundles you add still resolve against the new parent POM. Ask your team which upstream tag each production artifact was built from, and record it in the release notes.
Reviewing migration changes
Before rebuilding, read the migration guidance for every version between your current build and the target. Breaking changes, renamed properties and removed components change what your custom bundles must compile against and what your flows must reference. Record each change that touches a bundle you ship, and mark whether it needs a code change, a configuration change or no action. Treat this review as a required step in the upgrade checklist, not an optional read.
Retesting flows that use changed components
A successful Maven build does not prove that your flows still run. Build a list of every processor and controller service that your flows use from the optional bundles, and retest those flows against the new build in a non-production cluster. Focus on property names, default values, relationship names and scripted components, since these are the changes that break flows silently. Keep representative input data and expected outputs so each retest has a clear pass or fail result.
Rebuilding and re-signing artifacts
Every upgrade produces new archives that must be rebuilt, checksum-verified and signed with your organization's key before they reach an internal repository or a restricted network. Confirm that the build is reproducible from the recorded tag and profile list, and that dependency sources are pinned or mirrored internally. Store the build log and the hash of each produced file with the release record so an auditor or incident responder can trace what was deployed.
Tracking the 1.x to 2.x transition
If any environment still runs NiFi 1.x, the custom build must be planned for two lines, not one. The project states that the 1.x line cannot be maintained further because its Jetty, Spring and AngularJS dependencies cannot be upgraded in that line. Confirm the upgrade path for each environment, including the requirement to move through 1.27.0 before 2.0.0 and the change from flow.xml.gz to flow.json.gz. Do not add new bundles to a 1.x build that you expect to retire.
Planning for Registry deprecation
NiFi Registry is deprecated and planned for removal in NiFi 3.0, so any custom bundle or build step that depends on it will need a replacement before that release. Inventory where your build, deployment scripts and version control integration reference the Registry, and compare them with the Git-based Flow Registry Clients that NiFi 2 includes. Schedule this review alongside each 2.x upgrade so the replacement is tested before the Registry is removed.
Why the NiFi 2.x line changes the build plan
A custom distribution built on the 1.x line should be planned as a migration, not as a routine build. The NiFi project explains that 1.x cannot be maintained further because it depends on Jetty 9.4, Spring Framework 5.3 and AngularJS 1.8, and none of those can be upgraded within that line. Any Maven profile, NAR selection or assembly change you make today will need to be rebuilt against 2.x later, so the work of choosing bundles should be tied to the target version from the start. The current release is NiFi 2.12.0, released September 13, 2026, according to the NiFi download page, and that is the line to design against.
The migration path is strict. The NiFi migration guidance requires upgrading to NiFi 1.27.0 before moving to 2.0.0, and it changes the flow configuration file from flow.xml.gz to flow.json.gz. Your build pipeline must therefore produce a 1.27.0 artifact that can start and load your existing flows before any 2.x artifact is produced. Confirm with your own team which optional NARs your flows depend on, because any component that is removed, renamed or replaced in 2.x will break the assembly definition as well as the flows. Also confirm the Java runtime you will run on, since the administration guide lists Java 21 as the minimum for the current line.
Treat the custom build as a versioned artifact with an owner, a changelog and a test flow set that runs on both the 1.27.0 and 2.x builds. Plan the 2.x build before you finish the 1.x build, so that the bundle list, the Maven profiles and the migration checks are reviewed once rather than twice. Ask any partner for a written scope that names the source versions, the target version, the bundles in each build and the flow set used to verify them, because those choices determine the effort far more than the Maven work itself.
Security and supply chain controls for a custom build
A custom distribution puts your build pipeline in the trust path of every node that runs it. The controls below cover where the source comes from, what extra code the build pulls in, who can publish artifacts, how outputs are verified, and what the finished distribution exposes by default.
Build from a verified source tag
Start from a release tag of the apache/nifi repository whose signature and checksums you have verified, not from a moving branch. Record the exact tag and commit hash in your build manifest so every custom distribution can be traced to one source state. When you upgrade, repeat the verification against the new tag before you merge any profile changes. Confirm the verification steps against the project's current release documentation before you write them into your runbook.
Review dependencies added by profiles
Each Maven profile that adds a bundle, such as graph, media or gRPC support, can bring in transitive libraries that the convenience binary never shipped. Generate a dependency tree for the custom build, diff it against the stock build, and review every new artifact for license, maintenance status and known vulnerabilities. Keep the approved list in version control so a later profile change shows up as a reviewable diff.
Restrict who can publish artifacts
Decide which accounts and pipelines may publish built NAR and assembly artifacts to your internal repository or distribution store. Separate the people who change profiles from the identities that sign and publish, and require review before a profile change reaches the publishing job. Ask your platform team to confirm where repository write permissions are granted and who can rotate the signing keys.
Record checksums for every output
Generate checksums for the assembled archive and for each included NAR, and store them alongside the artifact in a location the deployment pipeline reads. Verify the checksums before every install, including on air-gapped hosts where the artifact was copied by hand. A mismatch should stop the rollout rather than prompt a manual override. Mismatched bundles are often the first sign of a rebuilt or tampered artifact.
Minimize bundles to reduce attack surface
Include only the bundles that your flows use. Every extra processor bundle adds code that runs inside the NiFi JVM, with access to flow data and credentials, and each one needs patching. Document the reason each bundle is present, and remove bundles whose flows have been retired. A smaller distribution also gives your security team fewer components to test and fewer advisories to track.
Keep the secure defaults in the build
When no security configuration is provided, NiFi binds to 127.0.0.1, so the UI is reachable only through the loopback interface. Do not change that default in the custom build to make first runs easier. Put TLS and an authentication provider in the deployment configuration, and test that a node started without them is not reachable from other hosts. Confirm the exact property names against the administration guide for your release.
Limits to confirm before committing to a custom build
Which Maven profile names apply to my target NiFi release?
Profile names are specific to each release line, so confirm them against the exact version you plan to run before you write any build scripts. Read the nifi-assembly module and the root pom.xml in the source tree for the tag you intend to build, and check the NiFi downloads page for the release that matches your plan. Do not assume a profile from one minor version carries over to another. Ask your build engineer to record the profile names and the source tag in the build repository so the choice is reproducible at the next upgrade.
Do I need Java 21 and Python 3.10 to 3.12 for a custom build?
The NiFi administration guide lists Java 21 as the minimum runtime, and it lists Python 3.10, 3.11 or 3.12 for the optional Python-based processors. Treat the Python requirement as applying only if your custom distribution includes those processors, because the guide describes Python processors as a beta feature. Confirm that your build hosts, your runtime hosts and any air-gapped mirror all carry the same supported versions, and document which processors you enable so that the Python dependency is only introduced when it is needed.
What network access does the build host need?
The build host usually needs access to Maven repositories to resolve dependencies and plugins, and it may need access to the source repository for the release tag. Confirm which repositories your organization allows, whether a internal artifact proxy can serve them, and whether the build can run fully offline once dependencies are cached. If the target network is isolated, plan a separate step that moves the verified artifacts across, and record checksums so that the offline copy matches what was built and reviewed.
Who supports a custom NAR or distribution after handover?
The Apache NiFi project supports its own releases, but a distribution you assemble with extra bundles is your artifact, so support for it sits with whoever maintains the build. Confirm in writing who receives vulnerability notices for included bundles, who rebuilds when a dependency is patched, and who answers when a bundle behaves differently from the convenience binary. A fixed-scope engagement can define these boundaries in the statement of work, and an ongoing retainer can cover rebuilds and upgrades, but the split must be agreed before work starts.
Are the third-party licenses in the optional bundles acceptable to us?
NiFi itself is released under the Apache License 2.0, but optional bundles can pull in dependencies that carry their own licenses, and those terms apply to your distribution. Ask your legal or open-source review team to inventory the transitive dependencies of each bundle you add, including the notice files that must travel with the artifact. Confirm whether any component requires attribution, has copyleft terms, or restricts commercial redistribution, and decide before the build whether that is acceptable for your use.
How do I keep a custom build aligned when NiFi upgrades?
Each upgrade can rename profiles, change dependency versions or move bundles between modules, so a custom build needs a repeatable process rather than a one-time script. Confirm that the team has a branch or tag strategy, a regression check that compares the built bundle list with the expected list, and a record of every override you made to the upstream build. Ask for a review step at each NiFi release, because the migration guidance for a new line may change configuration and processor behavior that your custom bundles depend on.
Can my team maintain the build without an outside partner?
Yes, if your team has Maven and Java build experience, access to the build hosts, and time to review each upstream release. The harder part is the ongoing discipline: tracking security notices for included bundles, testing the artifact on a non-production cluster, and documenting decisions so that the next person can rebuild it. Confirm whether your engineers have that capacity for each release cycle. If not, DeployOpen can plan and implement the build as a fixed-scope piece of work, or cover ongoing rebuilds and testing under a retainer.
What drives the cost and time of a custom distribution build?
The main drivers are the number of optional bundles, how many of their dependencies conflict with the base distribution, whether the build must run offline, how much testing your environment requires, and how many NiFi release lines you must support. Each of these adds work for the engineer and for the reviewer. Ask any provider for a quote that separates one-time setup from recurring rebuilds, lists the bundles in scope, states which environments are covered by testing, and names the NiFi version and profiles the quote assumes.
How DeployOpen scopes and delivers a custom NiFi build
DeployOpen plans, implements and documents self-hosted open-source platforms inside the client's own infrastructure, and a custom NiFi distribution follows the same pattern. The engagement starts with a written scope that names the bundles to add (graph, media, gRPC or others), the Maven profiles that will select them, the build host and artifact repository, the target NiFi release line, and who signs off on each stage. Most engagements are fixed-scope, so the deliverables, the handover format and the timeline are agreed in writing before build work begins. Ask for that document to list the build recipe, the exact artifacts produced, the test evidence for each bundle, and the runbook for repeating the build, so the result stays with your team after the engagement ends.
The delivery itself covers the work a single build cannot skip: confirming that each optional bundle is compatible with the chosen NiFi version, building the nifi-assembly module, checking the resulting distribution starts and loads the added components, and recording the checksums and dependency list that your security team will need to review. Documentation is part of the deliverable rather than an afterthought, so the runbook should explain how to reproduce the build, how to rebase it onto a new NiFi release, and which build settings were changed from the defaults. Where your environment is restricted, confirm with DeployOpen how the build output will be transferred into the network and how it will be verified there.
Upgrades and testing after the first delivery can be handled under a retainer. A retainer suits teams that expect to rebase the distribution on each new NiFi release, re-run compatibility checks when a bundle changes, or repeat the build for several environments. Ask the proposal to separate the one-time build from the recurring work, to state how new releases are reviewed and who decides whether a bundle is carried forward, and to define how urgent fixes are handled. DeployOpen does not issue audit reports or certifications for the resulting platform, so confirm with your independent assessor which evidence from the build and test records they will accept.
