Running on Docker

If you already use Docker, the easiest way to get your Nuts Node up and running for development or production is using Docker. This guide helps you to configure the Nuts node in Docker. To use the most recent master build use nutsfoundation/nuts-node:master (for production environments it’s advised to use a specific version or the latest build).

Published images are signed. See Verifying image signatures below to check that an image was built from the published source code.

First determine the working directory for the Nuts node which will contain configuration and data. These which will be mounted into the Docker container. Follow the configuration to setup the configuration of your node.

Mounts

Using this guide the following resources are mounted:

  • Readonly PEM file with TLS certificate and private key. They can be separate but in this example they’re contained in 1 file.

  • Readonly PEM file with TLS truststore for the particular network you’re connecting to.

  • Readonly nuts.yaml configuration file.

  • Data directory where data is stored.

Docker run

If you want to run without Docker Compose you can use the following command from the working directory:

docker run --name nuts -p 5555:5555 -p 1323:1323 \
  --mount type=bind,source="$(pwd)"/certificate-and-key.pem,target=/opt/nuts/certificate-and-key.pem,readonly \
  --mount type=bind,source="$(pwd)"/truststore.pem,target=/opt/nuts/truststore.pem,readonly \
  --mount type=bind,source="$(pwd)"/nuts.yaml,target=/opt/nuts/nuts.yaml,readonly \
  --mount type=bind,source="$(pwd)"/data,target=/opt/nuts/data \
  -e NUTS_CONFIGFILE=/opt/nuts/nuts.yaml \
  nutsfoundation/nuts-node:latest

This setup uses the following nuts.yaml configuration file:

strictmode: false
datadir: /opt/nuts/data
tls:
  truststorefile: /opt/nuts/truststore.pem
  certfile: /opt/nuts/certificate-and-key.pem
  certkeyfile: /opt/nuts/certificate-and-key.pem
network:
  bootstrapnodes:
    - example.com:5555

Note

The command above uses pwd and bash functions, which do not work on Windows. If running on Windows replace it with the path of the working directory.

You can test whether your Nuts Node is running properly by visiting http://localhost:1323/status/diagnostics. It should display diagnostic information about the state of the node.

Docker Compose

Copy the following YAML file and save it as docker-compose.yaml in the working directory.

version: "3.7"
services:
  nuts:
    image: nutsfoundation/nuts-node:master
    environment:
      NUTS_CONFIGFILE: /opt/nuts/nuts.yaml
    ports:
      - 5555:5555
      - 1323:1323
    volumes:
      - "./certificate-and-key.pem:/opt/nuts/certificate-and-key.pem:ro"
      - "./truststore.pem:/opt/nuts/truststore.pem:ro"
      - "./nuts.yaml:/opt/nuts/nuts.yaml:ro"
      - "./data:/opt/nuts/data:rw"

Start the service:

docker compose up

Verifying image signatures

Docker images of the Nuts node are built and pushed to Docker Hub by a GitHub Actions workflow. The workflow signs each pushed image with Sigstore cosign, using the identity of the workflow itself. A valid signature proves that the image was built by the CI pipeline of the nuts-foundation/nuts-node repository, from a specific commit. An image built on a developer machine and pushed with Docker Hub credentials does not carry a valid signature.

This section shows how to check a signature by hand, how to deploy a verified digest, and how to enforce verification in Kubernetes and in CI pipelines.

Note

Signing was introduced in 6.2.12 and 5.4.39; images of earlier releases are not signed. Security fixes are prepared in the private repository nuts-foundation/nuts-node-private and may be released before their source code is public. Images of such a release are signed with the identity of that repository’s workflow; the verification commands below accept both identities. The source code of an embargoed release becomes available in the public repository at disclosure.

Checking a signature with cosign

The pipeline signs with cosign 3. That version stores a signature as a Sigstore bundle, attached to the image through the OCI referrers API, instead of the sha256-<digest>.sig tag that cosign 2 used. cosign 2 does not find such a signature and fails with no signatures found, and so does any other verifier that only reads the tag. The Kubernetes and Azure sections below show which setting switches those verifiers to the bundle format.

Install cosign (version 3.0 or later) and verify a tag:

cosign verify nutsfoundation/nuts-node:latest \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp \
    '^https://github.com/nuts-foundation/nuts-node(-private)?/\.github/workflows/build-images\.yaml@'

cosign exits with code 0 and prints the verified claims when the signature is valid. The two flags pin the identity you trust:

  • --certificate-oidc-issuer: the identity provider. For images built on GitHub Actions this is always https://token.actions.githubusercontent.com.

  • --certificate-identity-regexp: the workflow that requested the signing certificate. Only the build-images.yaml workflow in the nuts-foundation/nuts-node repository, or in nuts-foundation/nuts-node-private for embargoed security releases, matches this expression.

Each signature is also recorded in the public Rekor transparency log, so anyone can audit when and by which workflow signatures were produced.

Deploying a verified digest

A tag such as latest or a version number is mutable: verifying a tag and pulling the same tag later can yield different images. To close that gap, deploy by digest. cosign prints the digest of the image it verified (this command requires jq):

DIGEST=$(cosign verify nutsfoundation/nuts-node:latest \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github.com/nuts-foundation/nuts-node(-private)?/\.github/workflows/build-images\.yaml@' \
  --output json | jq -r '.[0].critical.image."docker-manifest-digest"')
echo "nutsfoundation/nuts-node@${DIGEST}"

Use the printed reference in docker run or in docker-compose.yaml:

services:
  nuts:
    image: nutsfoundation/nuts-node@sha256:...

Enforcing verification in Kubernetes

The examples in this section and the Azure one below are meant to get you started, not to be pasted into production unchanged. They are written against the versions named with each example, and setups differ, so try them in your own cluster or pipeline first. If something turns out to be wrong or outdated, let us know or open a pull request.

An admission controller can reject any pod whose image does not carry a valid signature. The example below uses Kyverno. The Sigstore policy-controller offers the same enforcement through a ClusterImagePolicy; set signatureFormat: bundle on the authority there, for the same reason (policy-controller 0.14 or later).

apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
  name: verify-nuts-node-images
spec:
  webhookTimeoutSeconds: 30
  rules:
    - name: require-signed-nuts-node
      match:
        any:
          - resources:
              kinds:
                - Pod
      verifyImages:
        - imageReferences:
            - "docker.io/nutsfoundation/nuts-node*"
          type: SigstoreBundle
          failureAction: Enforce
          attestors:
            - entries:
                - keyless:
                    issuer: "https://token.actions.githubusercontent.com"
                    subjectRegExp: "^https://github.com/nuts-foundation/nuts-node(-private)?/\\.github/workflows/build-images\\.yaml@"

type: SigstoreBundle is what makes Kyverno read the signature from the OCI referrers API. Without it Kyverno uses its default type Cosign, which looks for the sha256-<digest>.sig tag and rejects every Nuts node image. Both type and the per-rule failureAction require Kyverno 1.13 or later.

The policy matches only Nuts node images; other images in the cluster are unaffected. Kyverno replaces the tag with the verified digest on admission, so the pod runs exactly the image that was verified. The cluster needs outbound access to Docker Hub for the signature, and to the Sigstore TUF repository (tuf-repo-cdn.sigstore.dev) for the trust root.

Azure

  • Azure Kubernetes Service (AKS): the Kyverno policy above works unchanged. Azure’s own Image Integrity feature (Azure Policy with Ratify) is not an alternative for these images: it is a preview feature that its documentation says not to use in production, Notation is its only supported verifier, and Audit is its only supported effect. It cannot check a cosign signature.

  • Azure Container Apps and Container Instances: these services have no admission control. Verify in the deployment pipeline and deploy by digest.

  • Azure DevOps pipelines: add a verification step before deployment. The step needs cosign 3.0 or later; pin the version rather than downloading latest.

steps:
  - task: Bash@3
    displayName: Verify nuts-node image signature
    inputs:
      targetType: inline
      script: |
        set -euo pipefail
        COSIGN_VERSION=v3.1.3
        curl -sLo cosign "https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64"
        chmod +x cosign
        DIGEST=$(./cosign verify "nutsfoundation/nuts-node:$(NUTS_VERSION)" \
          --certificate-oidc-issuer https://token.actions.githubusercontent.com \
          --certificate-identity-regexp '^https://github.com/nuts-foundation/nuts-node(-private)?/\.github/workflows/build-images\.yaml@' \
          --output json | jq -r '.[0].critical.image."docker-manifest-digest"')
        echo "##vso[task.setvariable variable=NUTS_IMAGE]nutsfoundation/nuts-node@${DIGEST}"

Later pipeline steps deploy $(NUTS_IMAGE), for example with the AzureContainerApps or KubernetesManifest tasks.

Provenance and SBOM

Each image contains SLSA build provenance and an SPDX software bill of materials, embedded as attestation manifests in the image index. The provenance records the source repository, the commit, and the build parameters. Inspect them with:

docker buildx imagetools inspect nutsfoundation/nuts-node:latest \
  --format '{{ json .Provenance }}'
docker buildx imagetools inspect nutsfoundation/nuts-node:latest \
  --format '{{ json .SBOM }}'

The attestations are part of the image index, so the cosign signature on the image digest covers them.

Scope of the guarantee

A valid signature proves that the image was built and pushed by the build-images.yaml workflow of the nuts-foundation/nuts-node repository (or nuts-node-private for embargoed security releases), at the commit recorded in the certificate, and that the image was not modified afterwards. For an embargoed release the commit is not publicly readable until disclosure; until then the signature proves the origin of the image but the source cannot be audited. It does not prove that the source code at that commit is free of defects or malicious changes. Review of the source code, and of who may change it, remains the basis of trust.