Skip to content

NATS JetStream FIPS Test Service

nats-sinks includes an optional first-party NATS JetStream test-service image for local smoke testing in environments that prefer repository-owned Oracle Linux 9 slim FIPS based service images.

The image is test infrastructure only. It is not a production NATS distribution, it does not replace the upstream NATS project images, and it does not change the runtime delivery contract. nats-sinks still acknowledges JetStream messages only after the configured sink has durably succeeded.

Image Construction

The Dockerfile is stored at:

examples/nats-jetstream-fips-test/Dockerfile

It uses:

container-registry.oracle.com/os/oraclelinux:9-slim-fips

as the only base image. During build it downloads the pinned upstream NATS Server release archive, verifies the published SHA-256 checksum, installs only the nats-server binary, and runs as UID/GID 10001.

The currently pinned NATS Server release is:

v2.14.1

The Dockerfile includes checksums for linux-amd64 and linux-arm64 release archives from the upstream nats-io/nats-server release checksum file. Other architectures fail closed until they are explicitly reviewed and added.

Running The Local Smoke Test

By default, the local Docker smoke test still uses the public NATS image for broad developer convenience:

python scripts/run-docker-local-smoke.py

To build and use the first-party Oracle Linux 9 slim FIPS NATS test-service image, run:

python scripts/run-docker-local-smoke.py --build-first-party-nats-image

If the first local build needs more time to pull Oracle Linux packages and the pinned NATS Server archive, raise the bounded build timeout:

python scripts/run-docker-local-smoke.py --build-first-party-nats-image --build-timeout-seconds 900

If nats-sinks:local is already built and the verification only needs to refresh the NATS service image, skip the project image build:

python scripts/run-docker-local-smoke.py --build-first-party-nats-image --skip-project-image-build

Expected successful output:

Local Docker smoke test passed: persisted 8 message(s) under /path/to/nats-sinks/.local/docker-file-sink.

The runner:

  1. Builds the local nats-sinks image.
  2. Builds examples/nats-jetstream-fips-test/Dockerfile as nats-sinks-nats-jetstream-fips-test:local.
  3. Starts the NATS service through Docker Compose with JetStream enabled.
  4. Publishes deterministic fake messages.
  5. Runs the file sink in the nats-sinks container.
  6. Waits for the expected fake output files.
  7. Removes the Compose stack and generated output unless preservation flags are used.

Use --nats-image when a controlled environment wants to supply an internally mirrored or pinned NATS test-service image:

python scripts/run-docker-local-smoke.py --nats-image registry.example.invalid/nats-test:approved

Do not put registry credentials, private registry hostnames, or internal image digests into GitHub issue comments or public reports.

Public Image Fallback

The public nats:2.10 image remains the default for ordinary local developer smoke tests. That keeps the simple path fast and familiar while allowing maintainers and controlled environments to opt into the first-party FIPS-based image for release evidence.

The public image is therefore still documented as an external test dependency, not as a first-party container asset. See Third-Party Test Service Image Review for the inventory and current replacement decisions.

Security Posture

The first-party NATS test-service image is intentionally narrow:

  • Oracle Linux 9 slim FIPS base image.
  • Pinned NATS Server release.
  • SHA-256 checksum verification during build.
  • Non-root runtime user.
  • JetStream enabled with local container storage.
  • No credentials, TLS material, private endpoints, subjects, or payloads baked into the image.

It is meant for local synthetic smoke testing. Production NATS deployment, authentication, authorization, TLS, account configuration, clustering, leaf nodes, gateways, monitoring policy, and persistence sizing remain operator responsibilities outside this test image.