Local Docker Development

In this section we will cover how to deploy a NEO•ONE Node locally using the NEO•ONE Node Docker image.

If you are unfamiliar with Docker or do not have a version installed locally visit their getting started page.


  • Docker
    • Minimum: at least 2GB Memory, 1cpu, and 50GB Storage allocated
    • Recommended: 4GB Memory, 2cpu, and 60GB+ Storage allocated (if you plan to deploy to a cluster you will need this for each pod/container)

Getting Started

Docker Repository on Quay

NEO•ONE uses quay to automatically build the docker image every time a new version is published.

After you have installed Docker, run the following in a terminal:

docker pull quay.io/neoone/node
docker run quay.io/neoone/node

Voila! You should now be running the most recent NEO•ONE Node in a local docker container and will see logs to confirm it has started.


There are several ways to configure the node; any rc type configuration is accepted. as an example we can set the monitor level of the node to verbose using either:

docker run quay.io/neoone/node --monitor.level=verbose

or through environment variables

docker run -e neo_one_node_monitor__level=verbose quay.io/neoone/node

Additionally you have the option of creating a config (no extension) file and mounting it directly to the container. By default the node will look for a config at /etc/neo_one_node.

So if we have a config

## /path/to/config
  "monitor": {
    "level": "verbose"

located at /path/to/config we could mount this to the default location as:

docker run -v /path/to:/etc/neo_one_node/ quay.io/neoone/node

(Note that you must mount the entire folder the config file is in)

After running any the above you should see more logging on startup! For more configuration options see the configuration reference.


Similarly to how we can mount a configuration folder to the container for local testing we can also mount a folder for storing the blockchain data our node will collect. By default, the node will use /root/.local/share/neo_one_node as its storage. We can mount a local folder /path/to/node-data/ using

docker run -v /path/to/node-data:/root/.local/share/neo_one_node quay.io/neoone/node

This is helpful when testing locally as you won’t have to re-sync your node-data on every restart.

Port Publishing

By default the container will be able to access external resources, such as connecting and syncing with other relay nodes after setting node.rpcURLs.

If you would like your local Docker container to be able to send its own data, you’ll need to publish the port using docker commands. As an example we can enable node metrics using the following command:

docker run -p 8001:8001 quay.io/neoone/node --environment.telemetry.port=8001

Upon visiting localhost:8001/metrics you should now see the node-metrics page.


By default metrics are disabled so you must include the --environment.telemetry.port=8001 argument or provide a telemetry port through other means of configuration (see above).


The following configurations should be a solid jumping off point for working with the node. For each of the three examples here we will also show how to implement them using Docker Compose.

In all three examples we will use

docker run -v /node-config/:/etc/neo_one_node/ -v /node-data/:/root/.local/share/neo_one_node quay.io/neoone/node

to mount our configuration and local data file before starting the node. Go ahead and create the two folders node-config and node-data if you would like to follow along.


To sync your node with other nodes on the network, you must specify them using the options.node.rpcURLs configuration setting. A list of current mainnet nodes can be found at: http://monitor.cityofzion.io/

## /node-config/config
  "options": {
    "node": {
      "rpcURLs": [

Now, if we apply this configuration we can begin to request block information from other nodes. After saving this to node-config/config, run the command listed above.

Upon successfully starting the node, you should begin to see relay_block events!


Its worth mentioning that syncing the entire blockchain can take a very long time. We recommend restoring to a recent backup (described below) and then syncing.


To download a backup of the most recent blockchain data and extract it you can configure the node using NEO•ONE’s public backup hosted on Google Cloud. We’ll specify bucket information and mark the restore option as true.

## /node-config/config
  "options": {
    "backup": {
      "restore": true,
      "options": {
        "gcloud": {
          "projectID": "neotracker-172901",
          "bucket": "bucket-1.neo-one.io",
          "prefix": "node_0",
          "maxSizeBytes": 419430400

This tells the node where we want to restore from. Assuming there is an available google-cloud bucket to restore from (there will be for our example) it will download and extract the blockchain data to our defined node-data folder. This process can take multiple hours depending on network speeds as a fully synced backup is ~16GB in size.

To restore and sync simply combine the above configurations.

Previous Article
Next Article