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 kizunano_node service run inside the container cannot be easily used. These options are available as of V20.

KIZUNANO COIN Directory¶

KIZUNANO COIN directory 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_DIR} indicated in the steps below will be the location of these files on your host machine.

Managing the Container¶

Starting¶

The following command will start the node container. Either set the specified environment variables (i.e. NANO_NAME=kizunano_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_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 3975:3975/udp \
  -p 3975:3975 \
  -p [::1]:3976:3976 \
  -p [::1]:3978:3978 \
  -v ${NANO_HOST_DIR}:/root \
  --name ${NANO_NAME} \
  kizunanocoin/node:${NANO_TAG}

Option	Purpose
`-d`	Starts the docker container as a daemon
`-p 3975:3975/udp`	Maps the network activity port
`-p 3975:3975`	Maps the bootstrapping TCP port
`-v ${NANO_HOST_DIR}:/root`	Maps the host's KIZUNANO COIN directory to the guest `/root` directory
`--restart=unless-stopped`	Restarts the container if it crashes
`kizunanocoin/kizn:${NANO_TAG}`	Specifies the container to execute with tag
`-p [::1]:3976:3976` or `-p 127.0.0.1:3976:3976`	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 kizunano_node.
`-p [::1]:3978:3978` or `-p 127.0.0.1:3978:3978`	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 3975 and 3976 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.

0118ad5b48489303aa9d195f8a45ddc74a90e8a7209fc67d5483aabf3170d619

Note

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 3975, both TCP and UDP are required.

Warning

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

Stopping¶

To stop your KIZUNANO COIN Node:

docker stop ${NANO_NAME}

Restarting¶

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        kizunanocoin/node   "/bin/bash /entry.sh"   41 seconds ago      Up 56 seconds       0.0.0.0:3975->3975/tcp, 0.0.0.0:3975->3975/udp, 127.0.0.1:3976->3976/tcp   kizunano_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 KIZUNANO COIN Node

docker pull kizunanocoin/node

Or pull the KIZUNANO COIN tagged with "V19.0" from Dockerhub

docker pull kizunanocoin/node: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}

Warning

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'
services:
  node:
    image: "kizunanocoin/node:${NANO_TAG}" # tag you wish to pull, none for latest
    restart: "unless-stopped"
    ports:
     - "3975:3975/udp"   #udp network traffic
     - "3975:3975"       #tcp network traffic
     - "[::1]:3976:3976" #rpc to localhost only
     - "[::1]:3978:3978" #websocket to localhost only
    volumes:
     - "${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:

Usage:
   /entry.sh kizunano_node [[--]daemon] [cli_options] [-l] [-v size]
     [--]daemon
       start as daemon either cli [--daemon] form or short form [daemon]
     cli_options
       kizunano_node cli options <see kizunano_node --help>
     -l
       log to console <use docker logs {container}>
     -v<size>
       vacuum database if over size GB on startup
   /entry.sh bash [other]
     other
       bash pass through
   /entry.sh [*]
     *
       usage
 default:
   /entry.sh kizunano_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=kizunanocoin -w=/home/kizunanocoin 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/kizunanocoin

This will be changed to default to USER kizunanocoin and WORK_DIR /home/kizunanocoin 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]:3976

Or the blockcount:

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

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" }' [::1]:3976 | jq ".blocks[].block_account"

For other commands, review the RPC Protocol details.

Troubleshooting¶

If you get Error starting userland proxy: port is not a proto:IP:port: 'tcp:[:'. or want to expose IPv4 port, use -p 127.0.0.1:3976:3976. Likewise, if you get curl: (7) Couldn't connect to server when interacting with the node, replace [::1]:3976 with 127.0.0.1:3976.

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.