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, 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.

If planning to use ufw with Docker, note that you may need to prevent Docker from manipulating iptables to properly manage firewall settings.

Nano Directory

The Nano directory contains:

  • Node wallet files (wallets.ldb, wallets.ldb-lock)
  • Configuration files
  • Log files
  • Ledger files (data.ldb and data.ldb-lock for default LMDB, or rocksdb directory with files for optional RocksDB backend)
  • Directory for wallet backups (backup)

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_DIR} 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.

  • ${NANO_HOST_DIR} - 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 \
  -p \
  -p \
  -v ${NANO_HOST_DIR}:/root \
  --name ${NANO_NAME} \
Option Purpose
-d Starts the docker container as a daemon
-p 7075:7075 Maps the bootstrapping TCP port
-v ${NANO_HOST_DIR}:/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
or -p[::1]:7076:7076
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.
or -p[::1]:7078:7078
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.



As of V21 peering and communicating via UDP has been disabled by default and is deprecated. The ability to use UDP will be removed from the node in a future release yet to be determined. For more information, see the network details.

On port 7075, only TCP is required since V21.


If you are running multiple nano_node Docker containers, DO NOT share the same ${NANO_HOST_DIR}, 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 specific version we need.

Pull a version of the nano node

docker pull nanocurrency/nano:V22.0

Lastly, we start up the docker container again using the same command but the with new version tag. Alteratively, you can use docker-compose.

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_DIR} 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 Compose

A sample docker-compose.yml is provided to model the same behavior as the docker cli examples above

version: '3'
    image: "nanocurrency/nano:${NANO_TAG}" # tag you wish to pull
    restart: "unless-stopped"
     - "7075:7075/udp"   #udp network traffic (deprecated since V21)
     - "7075:7075"       #tcp network traffic
     - "" #rpc to localhost only
     - "" #websocket to localhost only
     - "${NANO_HOST_DIR}:/root" #path to host directory

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"

Or the blockcount:

curl -d '{
  "action": "block_count"


On some systems it may be necessary to replace with IPv6 equivalent of [::1] when mapping Docker ports

In addition, you can make use of command-line JSON utilities such as jq to parse and manipulate the structured data retrieved from curl. For example the account information associated with certain block:

curl -s -d '{
  "action": "blocks_info",
  "hashes": ["87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9"],
  "json_block": "true" 
}' | jq ".blocks[].block_account"

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 Likewise, if you get curl: (7) Couldn't connect to server when interacting with the node, replace [::1]:7076 with

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.