Skip to content

Docker Management

Docker greatly simplifies node management. Below we will go over some of the best practices for managing your Docker Image.

Docker Limitations

Although Docker is a great choice for many setups, there are some limitations to be aware of:

  • It is not recommended to run a *nix container, such as the officially provided one, on a Windows host - there are known issues with handling ports which prevent proper communication with peers.
  • V19 and lower: Due to the startup script built into the Docker containers, Launch Options for the nano_node service run inside the container cannot be easily used. These options are available as of V20.

Nano Folder

The Nano folder contains: wallets file (wallets.ldb), log files, optional config files, ledger file (data.ldb) and related lock files.

Protect wallet and backup files

The built-in node wallet is for use in development and testing only. Those using it should take care in protecting access to the wallets.ldb file and backup files, whether encrypted or not, for added security.

For Docker setups, the ${NANO_HOST_FOLDER} indicated in the steps below will be the location of these files on your host machine.

Managing the Container


The following command will start the node container. Either set the specified environment variables (i.e. NANO_NAME=nano_node) or substitute in explicit values to the docker run command.

  • ${NANO_NAME} - The name that you would like to assign to the docker container.

  • ${NANO_TAG} - The version of docker image you will be running. For consumers, latest is acceptable, but for enterprise use, a manually set tag to the latest version number is recommended.

  • ${NANO_HOST_FOLDER} - Location on the host computer where the ledger, configuration files, and logs will be stored. The Docker container will directly store files such as config-node.toml and data.ldb into this directory.

docker run --restart=unless-stopped -d \
  -p 7075:7075/udp \
  -p 7075:7075 \
  -p [::1]:7076:7076 \
  -p [::1]:7078:7078 \
  -v ${NANO_HOST_FOLDER}:/root \
  --name ${NANO_NAME} \
Option Purpose
-d Starts the docker container as a daemon
-p 7075:7075/udp Maps the network activity port
-p 7075:7075 Maps the bootstrapping TCP port
-v ${NANO_HOST_FOLDER}:/root Maps the host's Nano directory to the guest /root directory
--restart=unless-stopped Restarts the container if it crashes
nanocurrency/nano:${NANO_TAG} Specifies the container to execute with tag
-p [::1]:7076:7076
or -p
Indicates that only RPC commands originating from the host will be accepted. WARNING: Without the proper IP configured here, anyone with access to your system's IP address can control your nano_node.
-p [::1]:7078:7078
or -p
Indicates that only the host can create a connection to the websocket server. Data throughput can be very high depending on configuration, which could slow down the node if available outside the host.

If you wish to use different ports, change the host ports in the docker run command; do not change the ports in the config-node.toml file.

This will start the docker container using host ports 7075 and 7076 and put the data in a permanent location in your hosts's home directory, outside the docker container. Upon successful startup, Docker will return the container's full ID. A typical ID will look something like the value below.



TCP is used for bootstrapping and UDP is used to stream live transactions on the network. For more information, see the network details.

On port 7075, both TCP and UDP are required.


If you are running multiple nano_node Docker containers, DO NOT share the same ${NANO_HOST_FOLDER}, each nano_node requires its own independent files.


To stop your Nano Node:

docker stop ${NANO_NAME}


If you need to restart your node for any reason:

docker restart ${NANO_NAME}

Checking Status

A list of currently running containers can be found by issuing the following command.

docker ps
CONTAINER ID        IMAGE               COMMAND                 CREATED             STATUS              PORTS                                                                      NAMES
0118ad5b4848        nanocurrency/nano   "/bin/bash /"   41 seconds ago      Up 56 seconds>7075/tcp,>7075/udp,>7076/tcp   nano_node_1

Updating the Docker Image

First, stop the container if it is running.

docker stop ${NANO_NAME}

Then we can download the latest version with docker pull (or whichever version we need).

Pull latest release of the Nano Node

docker pull nanocurrency/nano

Or pull the Nano Node tagged with "V19.0" from Dockerhub

docker pull nanocurrency/nano:V19.0

Lastly, we start up the docker container again using the same command.

Updating Node Configuration

First, stop the container if it is running.

docker stop ${NANO_NAME}


Modifications made to configuration files while the Docker container is running have no effect until the container is restarted.

You may now edit the configuration files located in ${NANO_HOST_FOLDER} using your preferred text editor.

Once modifications are complete, start up the docker container again using the same command.

Enable Voting

When setting up a new node, voting is disabled by default in the configuration file and must be manually enabled in order to participate in consensus. See enable_voting configuration option for more details.

Docker entrypoint support

As of v20.0, the docker entry script has migrated to a command with default arguments:

   / nano_node [[--]daemon] [cli_options] [-l] [-v size]
       start as daemon either cli [--daemon] form or short form [daemon]
       nano_node cli options <see nano_node --help>
       log to console <use docker logs {container}>
       vacuum database if over size GB on startup
   / bash [other]
       bash pass through
   / [*]
   / nano_node daemon -l

Docker USER Support

As of v20.0, the docker containers support the --user= and -w= flags.

To maintain existing compatibility the Docker containers are being built with USER ROOT and WORK_DIR /root

The problem with this is that the container ends up writing files to your mounted path as root. Best practices would dictate that since there is no need for privilege escalation we can create a user and run under that context instead.

In the event you wish to use the --user=nanocurrency -w=/home/nanocurrency flags the directory you mount should have permissions changed for uid:guid 1000:1000 using sudo chown -R 1000:1000 <local_path> and your mount flag will become -v <local_path>:/home/nanocurrency

This will be changed to default to USER nanocurrency and WORK_DIR /home/nanocurrency in a future release

RPC calls to the node

You can use the RPC interface on the local host via curl to interact with the node.

For example the version of the node:

curl -d '{ "action" : "version" }' [::1]:7076

Or the blockcount:

curl -d '{ "action" : "block_count" }' [::1]:7076

For other commands, review the RPC Protocol details.


If you get Error starting userland proxy: port is not a proto:IP:port: 'tcp:[:'. or want to expose IPv4 port, use -p

If you get create ~: volume name is too short, names should be at least two alphanumeric characters. replace the ~ with the full pathname such as /Users/someuser.