Run Fluentd in Docker on an offline network

For an offline environment, prepare the entire runnable image on a connected build host, including plugins and their dependencies. Transfer that image to the internal registry or load it directly. Merely downloading one plugin gem does not collect its transitive dependencies or native build requirements.

Build and export the approved image

Choose a Fluentd base version and plugin versions that your environment has approved. This Dockerfile makes those choices explicit at build time:

ARG FLUENTD_BASE
FROM ${FLUENTD_BASE}
USER root
ARG ES_PLUGIN_VERSION
RUN fluent-gem install fluent-plugin-elasticsearch \
    --version "${ES_PLUGIN_VERSION}" --no-document
USER fluent

Set FLUENTD_BASE to the selected image tag or digest and supply a compatible plugin version. Build on a connected host for the target architecture. If the plugin needs native libraries or build tools, include and verify them in that image before export.

Once the resulting image has been tested and tagged fluentd-custom:approved:

docker save -o fluentd-custom.tar fluentd-custom:approved
# After transferring the archive to the offline host:
docker load -i fluentd-custom.tar

Verify the transferred file's checksum and image identity through your normal artifact process. An internal registry can distribute the same image without rebuilding it at runtime.

If the image itself must be built offline

Prepare all required gem versions, their transitive dependencies, and any operating-system packages for the target Ruby and architecture. A local-install step can then use a reviewed dependency bundle:

ARG FLUENTD_BASE
FROM ${FLUENTD_BASE}
USER root
COPY gems/ /tmp/gems/
RUN fluent-gem install --local --no-document /tmp/gems/*.gem
USER fluent

gem fetch obtains a named gem, not a guaranteed complete dependency closure. Keep a manifest or lock-based packaging process and test the offline build with network access disabled. A prebuilt tested image is often simpler than transporting an incomplete build toolchain.

Mount configuration, inputs, and state

docker run -d --name fluentd \
  --mount type=bind,src=/opt/fluentd/conf,dst=/fluentd/etc,readonly \
  --mount type=bind,src=/var/log/myapp,dst=/var/log/myapp,readonly \
  --mount type=volume,src=fluentd-state,dst=/fluentd/state \
  -p 127.0.0.1:24224:24224 \
  fluentd-custom:approved fluentd -c /fluentd/etc/fluent.conf

This publishes TCP only on host loopback for local senders. Choose a controlled internal address and appropriate TLS/authentication when remote hosts send logs; publish UDP only if your configured protocol or heartbeat behavior requires it. The forward source must listen on the correct container interface.

Configure tail position files and persistent output buffers under /fluentd/state, with permissions for the runtime user. A read-only input mount cannot hold a writable position file. Ensure the output destination, DNS, certificates, and time synchronization also work without internet access.

FAQ

How do I detect missing plugins or configuration errors?

Run the image with the same mounts and fluentd -c /fluentd/etc/fluent.conf --dry-run. This checks configuration loading; then send a test event and verify delivery, buffering, and restart recovery. Dry-run success alone does not prove endpoint reachability or native plugin behavior under load.

Why is a Compose service name unreachable from Docker's logging driver?

The driver connects from the daemon's network context, not from the application container. Use an address reachable by that daemon, even if application-to-application traffic uses a private container network.

Does offline time synchronization matter?

Yes. Use an internal trusted time source so timestamps, TLS validation, and event correlation remain meaningful.

Reference: Fluentd container deployment.