Running on Docker

This guide helps you to configure the Nuts node in Docker. To use the most recent release use nutsfoundation/nuts-node:latest. For production environments it’s advised to use a specific version.


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 8080:8080 -p 8081:8081 \
  -e NUTS_STRICTMODE=false -e NUTS_HTTP_INTERNAL_ADDRESS=":8081" -e NUTS_URL="http://nuts" \

Docker Compose

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

    image: nutsfoundation/nuts-node:latest
      NUTS_STRICTMODE: false
      NUTS_URL: http://nuts
      - 8080:8080
      - 8081:8081

Start the service:

docker compose up


If your use case makes use of did:nuts DIDs, you also need to export port 5555, which is used for gRPC traffic by the Nuts network, and add a volume mount for data on /nuts/data (see below).

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


The default user in the container is 18081 that is only part of group 18081. This is a regular user without root privileges to provide an additional level of security. If datadir config value points to a mounted directory, see the section below how to manage privileges needed by the nuts-node.

Volume mounts

The default working directory within the container is /nuts that provides defaults for the various configurable data and config paths used:

  • /nuts/config/: Contains all configuration files.

    Any file changes will take effect after a node restart. It is recommended to set read-only privileges (default) to this directory and its contents for additional security. (chmod -R o+r </path/to/host/config-dir> assuming the directory on the host is not owned by user and/or group 18081)

  • /nuts/data/: Storage directory for data managed by the nuts-node.

    The container user (18081) has insufficient privileges by default to write to mounted directories. The required permissions can be granted by making the container user the owner of the data directory on the host. (chown -R 18081:18081 </path/to/host/data-dir>)


  • Nodes running the recommended deployment (external storage configured for and storage.sql.connection) that do not use did:nuts / gRPC network don’t need to mount a data dir.

  • “User 18081 already exists on my host.” See docker security (or relevant container orchestration platform) documentation how to restrict privileges to a user namespace / create a user mapping between host and container.

Development image

There’s also a development image available which includes an HTTPS tunnel. This is useful for development and testing purposes. In order to use it, you need a Github account. The development image is available at Docker hub under nutsfoundation/nuts-node:dev.

You can also build the development image yourself by running the following command in the root of the repository:

make docker-dev

When starting up the development image, it’ll block and requires you to authenticate with Github. It’ll print a URL to visit in your browser and a code to enter. After authenticating, the tunnel will be established and the Nuts Node will start. To save the tunnel configuration, mount a directory to /devtunnel inside the container. The last used tunnel is stored in /devtunnel/ devtunnel/tunnel.log contains the logs of the tunnel including the public accessible URL. This URL is also printed to the console.