Apache NiFi in Docker: Setup and Configuration

Running Apache NiFi in Docker: when a container fits your plan

The apache/nifi image runs a single standalone NiFi instance, and most of its behavior is set through environment variables passed to the container. A team that needs flows running quickly for development, testing or a single-node production workload can use it well, provided it sets its own credentials on the first start. If SINGLE_USER_CREDENTIALS_USERNAME and SINGLE_USER_CREDENTIALS_PASSWORD are not set, the image generates a random username and password and writes them to the application log. Anyone who can read container logs can then sign in, so the first decision is to inject these values from a secret store at deployment time. The password must be at least 12 characters, so confirm your secret generator meets that rule before the first run.

Choose a container deployment when one NiFi node is enough for the throughput, recovery window and maintenance tolerance you have agreed with the business. Development and test environments benefit most, because the same image and environment variables can be reused across pipelines and recreated quickly. Single-node production works when you accept that the node is a single point of failure, that restarts pause flows, and that you own backups of the flow configuration and repositories. The Docker Hub page states that the image currently supports standalone mode, so do not plan a clustered topology on this image alone.

Plan for a cluster or a different topology before the flows grow. Clustering needs coordination through ZooKeeper or Kubernetes state, and the sizing, TLS between nodes and load balancer affinity all change the design. Confirm the current cluster support and any supported Kubernetes approach with the NiFi project and the image documentation before you commit, since image capabilities change between releases. Also check the Docker Hub listing for the image tags and environment variables that match the NiFi version you intend to run, and confirm that your organization's policies allow pulling the image into your registry.

Which environment variables control ports, TLS, LDAP and heap

This table lists the documented apache/nifi environment variables, what each one controls, when it fits and what the team should confirm before relying on it. Read each row alongside the image's own variable list, because the image only exposes the settings its maintainers have documented. The main takeaway is that credentials, TLS and authentication choices should be decided before the first start, not after.

Variable	What it controls	When it fits and what to confirm
SINGLE_USER_CREDENTIALS_USERNAME	Sets the username for the single-user login. If unset, the image generates a random username at startup and writes it to the application log.	Set it for any non-throwaway container so the login is known and reproducible. Confirm that the team stores it in a secrets manager and that log access is restricted.
SINGLE_USER_CREDENTIALS_PASSWORD	Sets the single-user password. If unset, the image generates a random password and writes it to the log.	Set it from a secret source, not a plain compose file. The password must be at least 12 characters, so confirm your secret generator meets that length before deployment.
NIFI_WEB_HTTPS_PORT	Sets the port the NiFi web UI listens on for HTTPS.	Use it when the default port conflicts with other services or when a reverse proxy or load balancer expects a specific backend port. Confirm the port mapping in the container runtime matches this value.
NIFI_JVM_HEAP_INIT	Sets the initial Java heap size for the NiFi JVM.	Set it together with the maximum heap so the JVM starts at a predictable size. Confirm the value fits within the memory limit assigned to the container, since heap alone does not cover off-heap use.
NIFI_JVM_HEAP_MAX	Sets the maximum Java heap size for the NiFi JVM.	Size it against the container memory limit and the flow's queue and processing load. Confirm the value with your performance testing, because an oversized heap can slow garbage collection and an undersized one can cause out-of-memory failures.
INITIAL_ADMIN_IDENTITY	Sets the identity that receives initial administrative rights on first start, used with certificate or directory-based authentication.	Use it when you move beyond single-user login. Confirm the identity string matches exactly what your authentication provider presents, such as a certificate subject or directory principal.
LDAP settings	Configure a directory-based login provider, including the directory server connection and user search parameters.	Use them only if the image variables cover the directory structure and bind method you need. Confirm the LDAP variables expose your required options, such as TLS to the directory, group handling and search filters, and check the image documentation for the current variable names.

Which authentication path fits your environment

A local evaluation or lab is the simplest path. The image runs in standalone mode with one administrative identity, which suits a proof of concept, a flow prototype or a training environment where only the builder signs in. You can let the image generate credentials, but those values are written to the application log, so most teams set SINGLE_USER_CREDENTIALS_USERNAME and SINGLE_USER_CREDENTIALS_PASSWORD explicitly and keep them in a secrets store.

Credential handling: the password must be at least 12 characters, and it should not appear in compose files committed to source control.
Shared access: one account means no per-person audit trail, so keep this path away from anyone who needs individual accountability.
Network exposure: publish the port only to the host or a lab network, since a single shared login is a weak control on a routable address.
Data lifetime: lab flows often hold sample data, so decide how volumes are wiped and rebuilt when the lab ends.
Migration cost: moving later to directory or certificate sign-in changes the container environment and user mapping, so document the lab settings for reuse.

Before you rely on this path, confirm in the image documentation for your version which single-user variables are honored and how the generated values behave when they are unset.

A team that needs named accounts usually points NiFi at an LDAP directory through the LDAP environment variables the image exposes. Users then sign in with their directory identity, access follows group membership, and leavers lose access when their directory account is disabled. The trade-off is that the directory becomes a dependency: its availability, bind account rights and certificate trust all affect whether anyone can reach the UI.

Bootstrap administrator: set INITIAL_ADMIN_IDENTITY to a named account so someone can grant policies after the first start.
Bind account: use a read-only service account with the narrowest search scope that works, and store its secret outside the image.
TLS to the directory: plan LDAPS or StartTLS and the trust chain for the directory certificate before the first login test.
Group mapping: agree on which directory groups map to NiFi policies, since broad groups quietly grant broad flow access.
Failure mode: test what happens when the directory is unreachable, because operators may need a break-glass path.

Before committing to this path, confirm which LDAP variables the image sets directly for your version and which need custom configuration files, and check the authentication provider options in the NiFi administration guide.

Why the image targets standalone mode and what that means for clusters

The apache/nifi image currently supports standalone mode, so a NiFi container you start from it is a single node with one set of repositories, one flow and one web endpoint. Teams that plan a containerized NiFi as if it were a cluster member will find that the image does not give them one. Before you design availability, scaling or maintenance around Docker, confirm the current image capabilities on the apache/nifi image page on Docker Hub, because the supported modes are stated there and can change between releases.

The consequences are practical. A single node has no peer to take over its flows, so a container restart, a host failure or an image upgrade stops processing until the node is back. Scaling means a bigger host and a larger JVM heap, not more nodes behind a load balancer. Maintenance windows must cover the time to stop the container, pull the new image, and confirm that the persisted flow.json.gz and repositories load cleanly. Ask whether your data sources can buffer during that window, and whether the NiFi queues and provenance repository on the volume are sized to hold the backlog you expect.

If you need multiple nodes, NiFi clusters can coordinate through an embedded or external ZooKeeper ensemble, or on Kubernetes through ConfigMaps or Leases for state and leader election, as described in the NiFi System Administrator's Guide. Those topologies require cluster configuration that the standalone container image does not provide out of the box, so they are a separate build and operations decision. Plan the cluster design with your platform team, confirm which mechanism your Kubernetes distribution and network policy support, and treat any clustered topology as a new deployment to be tested, not a scaled-out copy of the single container.

How to run NiFi in Docker step by step

This sequence takes a team from an empty Docker host to a running NiFi single-user instance with known credentials, a flow that survives restarts, and a UI reachable on the interface the team chose. Each step ends with a check that the team can repeat.

Pick and pin the image tag
The platform engineer selects an apache/nifi tag that matches a NiFi release the team has tested, then records that exact tag in the deployment manifest. Avoid floating tags such as latest in production, so a routine image pull cannot change the running version. Check the supported tags on the apache/nifi Docker Hub page before pulling. The image currently runs in standalone mode, so confirm that a single-node design meets your availability needs. Done when docker image inspect reports the pinned tag and the change record names it.
Set credentials from a secret store
The platform engineer passes SINGLE_USER_CREDENTIALS_USERNAME and SINGLE_USER_CREDENTIALS_PASSWORD from the team's secret store or orchestrator secrets, and keeps them out of version-controlled files. If these variables are missing, the image generates a random username and password at startup and writes them to the application log. The password must be at least 12 characters. Confirm with your security team how the secret is injected at runtime. Done when the startup log contains no generated credential and the supplied account signs in to the UI.
Map the web port and TLS settings
The platform engineer sets NIFI_WEB_HTTPS_PORT, publishes that port through the container's port mapping, and mounts the certificate and key material for HTTPS as read-only files. Confirm the certificate file locations and formats in the image documentation before mounting. Choose the host interface for the published port according to your network design. Done when docker port lists the published HTTPS port and the mounted certificate files open without permission errors inside the container.
Mount volumes for repositories and flow files
The platform engineer creates named volumes or host paths for the NiFi repositories, the configuration directory and the flow directory, then mounts each one into the container. In NiFi 2 the flow definition is stored as flow.json.gz, so the flow directory needs a volume of its own. Confirm the container paths in the image documentation before you write the run command. Done when a test file written to the flow directory appears in the matching host path.
Size JVM heap values to the host
The platform engineer sets NIFI_JVM_HEAP_INIT and NIFI_JVM_HEAP_MAX from the memory the host can give the container. Leave headroom for the operating system, sidecar containers and the page cache that the repositories rely on. Set the container memory limit above the maximum heap so the JVM is not terminated by the runtime. Size against the expected queue and content volume, and review performance guidance in the NiFi System Administrator's Guide. Done when the JVM arguments in the startup log match the values you set.
Start the container and test the UI
The platform engineer starts the container with the pinned tag, credentials, port mapping, volumes and heap settings, then opens the UI from a browser on the network the container is published to. If security is not configured, NiFi binds to 127.0.0.1, so the UI answers only on the loopback interface and remote connections fail. Check the bind address before troubleshooting the network. Done when the login page loads at the HTTPS address and the configured account signs in.
Check the startup state in logs
The platform engineer reads docker logs from the first minutes after start and looks for the message that confirms NiFi has finished starting. Review any errors about the keystore, port binding, repository locks or flow loading, and fix each one before moving on. Confirm that no generated credential appears, since the team supplied its own in an earlier step. Done when the log shows a clean startup and no errors repeat over several minutes of running.
Confirm the flow survives a restart
The platform engineer adds a simple test process group on the canvas, stops the container with docker stop, and starts it again using the same volumes and settings. After the restart, the process group and its configuration should still be present, and the flow file in the flow volume should reflect the change. Done when the flow reloads unchanged after the restart, which confirms the volume mappings work as intended.

What to persist in volumes and why it matters

A NiFi container is disposable only if its state lives somewhere else. Each item below is state the running instance writes after startup, so losing it means rebuilding flows, re-keying secrets or losing data in flight. Confirm the mount point, owner and permissions of each path against the apache/nifi image before you map volumes.

Flow configuration file

In NiFi 2 the flow definition is stored as flow.json.gz, which holds every process group, processor, connection and controller service you have built in the UI. If this file is not on a volume, each new container starts from the flow shipped with the image or an empty canvas. Confirm the path NiFi reads and writes inside the container, and confirm that the file is owned by the user the image runs as, so NiFi can write changes after each edit.

Content and FlowFile repositories

The content repository holds the payload of every FlowFile in flight, and the FlowFile repository tracks their attributes and queue state. Without persistent storage, a restart or replacement drops queued data, and records already accepted from a source may not be delivered downstream. Check that each repository is mapped to its own volume with enough capacity for your queue thresholds, and that the disk is monitored, because a full repository stops ingestion.

Provenance repository

The provenance repository records the lineage of each FlowFile: where it came from, what changed it and where it was sent. Auditors and incident responders depend on this history, and it is lost when the repository is not persisted. Confirm its location, its retention settings and how much disk it can consume, since provenance growth is often the first cause of a full volume. Decide in advance who may read this data, because it can contain sensitive attribute values.

Configuration directory

The configuration directory holds nifi.properties, the authorizer and login identity settings, and the keystore and truststore references used for TLS. Keys and identity mappings generated at first start are written here, so a replaced container without this state can lock out administrators or fail to match existing certificates. Confirm which files the image generates and which ones you supply, and keep your own copies under version control with secrets removed.

Logs directory

NiFi writes nifi-app.log, nifi-user.log and bootstrap logs to a logs directory. These are the first evidence during an outage or a security investigation, and they disappear with the container unless the path is mounted. Confirm the log location, the rotation settings, and that your log collector can read the mounted path. Do not rely on container log drivers alone, because they do not capture the NiFi user audit trail in the same form.

Custom NAR files

Custom and optional NARs are the extensions your flows depend on, and they are not part of the base image. If they are baked into a single image build without a persistent location, a rebuild can change the processor set between replicas. Decide whether NARs are copied into the image at build time or placed on a mounted directory, and confirm the directory NiFi loads them from and that the file ownership matches the NiFi user.

Keeping the container deployment locked down

The most common container security failure with NiFi is leaving credentials where they can be read later. If SINGLE_USER_CREDENTIALS_USERNAME and SINGLE_USER_CREDENTIALS_PASSWORD are not set, the image generates a random login and writes it to the application log, so anyone with log access can sign in as the administrator. Set both variables from your secrets manager or an orchestrator secret, and confirm with docker logs that no generated credential was printed. Avoid passing the password as a plain command-line argument, since it can end up in shell history and in process listings. Pass it through an environment file with restricted permissions or a secret mount, and rotate it if it was ever typed into a terminal or pasted into a ticket.

Port publishing needs deliberate choices. NiFi binds to 127.0.0.1 when no security configuration is provided, so a container started without the HTTPS settings will not be reachable from other hosts even if you publish the port. Once you configure NIFI_WEB_HTTPS_PORT and TLS, the interface listens on the address you configure, and anything you publish with -p becomes reachable from the network segment the host sits on. Publish only the HTTPS port, bind it to a specific host interface where your runtime allows it, and confirm with a port scan from outside the intended network. Keep the TLS keystore and its password out of the image and out of version control. Mount the keystore read-only, restrict its file permissions to the NiFi user, and treat the keystore password as a secret with its own rotation record.

Volumes hold the flow definitions, the provenance and content repositories, and the state that can contain sensitive data, so restrict who can read them on the host. Check the numeric user and group ID the container runs as, match host directory ownership to it, and deny read access to other local accounts. Keep the host itself patched and limit who has Docker daemon access, because that access is effectively root on the machine. For image updates, pin to a specific tag, record its digest, read the release notes before moving forward, and test the upgrade against a copy of your flow and repositories. Note that the image currently supports standalone mode only, so plan your clustering separately. Hardening tasks such as authorization policies, sensitive value handling and encryption are covered in depth on the Apache NiFi security hardening pages.

Limits to confirm before you commit to a container

The apache/nifi image makes a few deployment choices for you, and the NiFi project has several deprecations and runtime requirements that affect how long a container build will stay supportable. Confirm each item below against your own topology, runtime standards and upgrade plan before you write the Compose file or Helm values.

Supported topology is standalone

The image's Docker Hub page states that it currently supports running in standalone mode. If your design needs a multi-node cluster with coordinated state and leader election, a single container built from this image does not cover it. Confirm with the image maintainers whether clustering is on their roadmap, and decide whether a cluster will run from a different packaging path. Map this to your availability requirement before you size the host.

Java 21 and Python runtime

The administration guide lists Java 21 as the minimum runtime. If you plan to use the optional Python-based processors, it lists Python 3.10, 3.11 or 3.12. Check that your base image, patch policy and vulnerability scanner accept these versions before you pin a tag. Confirm also whether your organization allows a Python runtime inside the same container as the Java process.

Python processors are beta

The administration guide describes the Python-based processors as a beta feature. Do not build production flows that depend on them until you have tested the specific processors, their dependencies and their behavior across restarts. Decide whether your change process will accept a beta component in a regulated environment, and document that decision with the flows that use it.

Kerberos provider is deprecated

NiFi supports single-user, LDAP, OpenID Connect, SAML 2.0 and X.509 client certificate authentication, while the Kerberos provider is deprecated according to the administration guide. If your directory or security standard relies on Kerberos sign-in, confirm an alternative provider before you map environment variables for LDAP or other settings in the container. Avoid building a login design around a provider the project is moving away from.

NiFi Registry deprecation

The NiFi downloads page notes that NiFi Registry is deprecated and planned for removal in NiFi 3.0. If your container workflow depends on a Registry container for version control, confirm which Flow Registry Client you will use instead, such as the GitHub or GitLab clients, and plan the move before you standardize the volume layout and deployment pipeline around Registry.

Migration path from 1.x

If you are starting from an older NiFi release, the migration guidance requires upgrading to NiFi 1.27.0 before moving to 2.0.0, and changing the flow configuration file from flow.xml.gz to flow.json.gz. Confirm which version your existing volumes contain before you mount them into a 2.x container, because a volume written by an older release cannot simply be reused. Plan this step as a separate, tested upgrade.

What buyers ask before running NiFi in Docker

Can I run the apache/nifi image in production?

Yes, the image can serve production workloads, but it is built around standalone mode and it ships with defaults that a production deployment must replace. The image currently supports standalone operation, so a multi-node cluster needs a different topology. Before go-live, your team should confirm the image tag you will pin, replace the generated single-user credentials with managed secrets, enable HTTPS, and place the repositories and configuration on volumes you back up. A container that runs with the defaults is a test environment, not a production one. DeployOpen works from your written requirements and your own infrastructure, and it can confirm the production configuration against your risk model before anything is deployed.

How does a standard container deployment compare with a secured multi-node build?

A standard single-node container is mostly configuration: environment variables, a volume layout and a reverse proxy or TLS setup. A secured multi-node build adds clustering, a coordination layer, an identity provider, certificate management, sizing and failover testing, so effort grows with each of these. Standalone mode in the image does not cover clustering, so a cluster needs a deliberate design choice made before the build starts. The gap between the two is therefore architectural, not a matter of adding a few more variables. Ask for the topology decision to be written into the scope so both options are priced from the same requirements.

What does my team need to provide for a NiFi container engagement?

Your team typically provides access to the target container platform, the identity source you want NiFi to use, certificate authorities or a decision on who issues certificates, storage classes or volume locations, and a named owner for the flows and data that will run on the instance. Security and network teams also need to confirm allowed ports, DNS names and any outbound endpoints that flows will call. Access to a non-production environment early in the work reduces rework. Confirm these inputs in the written scope so that delays on your side are visible and tracked.

Can my team deploy NiFi in Docker using only the documentation?

A capable platform team can deploy a single standalone container from the Docker Hub page and the NiFi administration guide, provided it has time to test and the skills to run it afterward. The harder part is the set of decisions around credentials, TLS, authentication, repository persistence, JVM sizing and upgrade handling, and these decisions are where internal teams most often miss a step. Ask yourself whether someone on the team will own the upgrade path and the backups after go-live. If the answer is uncertain, a scoped engagement with a handover and runbook can cover the gap. Either route should end with a tested restore of the repositories.

How is the scope and quote for a NiFi Docker engagement set?

The scope is agreed in writing before work starts, and the quote follows from that document. DeployOpen does not publish a price list, so the quote depends on the requirements you define. A written scope should name the topology (standalone or clustered), the authentication provider, the certificate approach, the volumes and backup method, the environments covered, the handover materials and the acceptance tests. Ask for each of these to be listed as a separate deliverable so you can see what is included and what is excluded. Ongoing support, upgrades and continuous testing are available as separate retainers.

What drives the effort of a NiFi Docker deployment up?

Effort rises with the number of integration points, the authentication model, and the strictness of your control requirements. The main drivers are:

Authentication: a single-user account is quick to set up, while LDAP, OpenID Connect, SAML 2.0 or X.509 client certificates add directory mapping, testing and policy work.
Topology: clustering adds coordination, certificate and failover testing on top of the single-node build.
Data handling: flows that touch sensitive data need encryption, sensitive-value handling and provenance review.
Operations: backup, monitoring and upgrade procedures add work that recurs after go-live.

Your requirements document is the most effective way to control these drivers.

Which NiFi version should I pin for a new Docker deployment?

New deployments should target NiFi 2, because the NiFi downloads page states that NiFi 1.28 is the last minor release of the version 1 series and strongly encourages users to upgrade to NiFi 2. Version 1.x depends on Jetty 9.4, Spring Framework 5.3 and AngularJS 1.8, which the project cannot upgrade within that line. Confirm the exact image tag against the current release list before you pin it, and record the Java 21 requirement in your build. If you have existing 1.x flows, the migration path runs through 1.27.0 first, so plan that work as a separate step.

How DeployOpen scopes and delivers NiFi container deployments

DeployOpen plans, builds, hardens and documents NiFi containers inside your own infrastructure, starting from a written scope that names the image, the security settings and the storage layout. Engagements are fixed-scope, so the deliverables and the handover are agreed before work begins.

How we scope

Confirm whether the deployment will run in standalone mode, which the apache/nifi image currently supports.
Record the authentication method, whether single-user, LDAP or OpenID Connect, and who administers access.
Define volume layout for repositories, configuration and logs, and the JVM heap sizing agreed with your team.

How we build

Pin the image tag, set credentials through secrets rather than generated log output, and enforce a password of at least 12 characters.
Configure HTTPS ports, TLS material, LDAP settings and initial admin identity through documented environment variables.
Test restarts, volume persistence and container recreation so flows and repositories survive an image upgrade.

How we hand over

Deliver a runbook covering container start, stop, credential rotation, volume backup and log locations.
Document every environment variable, mount path and heap setting used, with the reason each value was chosen.
Walk your operators through the deployment and record what remains your responsibility after handover.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer, sized to the written scope.
Plan image upgrades against the NiFi migration guidance, including the NiFi 2 changes that affect flow configuration.
Confirm with your team which monitoring, backup and access-review tasks stay in-house and which move to a retainer.

Running Apache NiFi in Docker