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.
Examples
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" \
nutsfoundation/nuts-node:latest
Docker Compose
Copy the following YAML file and save it as docker-compose.yaml
in the working directory.
services:
nuts:
image: nutsfoundation/nuts-node:latest
environment:
NUTS_STRICTMODE: false
NUTS_URL: http://nuts
NUTS_HTTP_INTERNAL_ADDRESS: :8081
ports:
- 8080:8080
- 8081:8081
Start the service:
docker compose up
Note
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/health
. It should
display health information about the state of the node.
User
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 group18081
)
- /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 thedata
directory on the host. (chown -R 18081:18081 </path/to/host/data-dir>
)
Note
Nodes running the recommended deployment (external storage configured for
crypto.storage
andstorage.sql.connection
) that do not use did:nuts / gRPC network don’t need to mount adata
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.
The container stores the last used tunnel in /nuts/config/devtunnel/tunnel.id
.
/nuts/config/devtunnel/tunnel.log
contains the logs of the tunnel including the public accessible URL. This URL is also printed to the console.
Devtunnel also stores some session information in /nuts/DevTunnel
.
To persist a tunnel URL over node restarts, mount a directory at /nuts/config/devtunnel
(or one of its parents) inside the container.
Mounting /nuts
would also persist the current Github session over container restarts.
For trouble shooting devtunnel issues, see the documentation and tunnel usage limits.