How to setup a dedicated Nxt node
on a Raspberry Pi 2

Posted by Daniel Mross on January 4, 2016

Nxt is one of the most impressive and under-appreciated peer-to-peer networks on the internet. It is an open-source public blockchain platform that introduced a novel proof-of-stake consensus algorithm and it has survived in the wild for over 2 years. Today, the technology pioneered by Nxt is being used in well-funded projects like Ethereum, while Nxt itself remains under-the-radar.

The Nxt developers are continually working hard on releasing new features and improving scalability. The API continues to expand, while the software requires minimal system resources to operate. A block-generating "full node" can run on a Raspberry Pi model B and only costs about $50 in parts, and if you are reading this post you probably want to set up your own, so lets get started.

You'll need the following:

  • Raspberry Pi 2 or 3 (model B)
  • 8GB+ microSDHC card (Class 6 or higher recommended)
  • Micro USB cable for power
  • Cat 5 network cable or USB wifi adapter
  • USB keyboard, monitor + HDMI cable (initial setup only)

Installing the OS

We will be using Linux because it is reliable, secure and free. Raspbian is the most widely used flavor of Linux for Raspberry Pi devices and it is well supported and maintained. As of this writing, the latest version of Raspbian as of this writing is "Jessie", which is available for download on RaspberryPi.org. This will be a dedicated node and the client will only be accessed remotely, so I recommend using Raspbian Lite since we won't need a window manager.

There are a variety of ways to write the image to your microSDHC card and the installation guide covers Linux, OS X and Windows.

"It's easy once you've done it..."

OS Configuration

Once your microSDHC card is ready, you can boot your Raspberry Pi for the first time. Insert the memory card, plug in your USB keyboard, ethernet cable and HDMI connection first, then power on the Raspberry Pi by plugging in the micro USB cable. Many consumer routers sold today provide a USB port that should be able to power the Raspberry Pi 2, but if you are running a Raspberry Pi 3 or using USB peripherals (e.g. USB wifi) you should use a good 2.0A+ USB A/C adapter.

After the system boots you should see the login prompt. The default username is pi and the default password is raspberry. Once you are logged in, run the following to install the latest OS updates:

sudo apt-get update
sudo apt-get upgrade

Next, start the OS configuration utility by typing the following:

sudo raspi-config

The first thing to do is change the default password to something secure. Choose "2 Change User Password" and follow the prompts to set a new password.

Select "9 Advanced Options"

Since we aren't using a window manager we can reallocate some of the GPU memory to the OS. Select "A3 Memory Split" and set the value to 16.

If you want to be able to access your node from another computer via SSH you can enable the service under "A4 SSH". I highly recommend hardening your SSH installation once you have everything working.

Finally, select option "1 Expand Filesystem" to rewrite the partition table of your microSDHC card and use the full storage capacity.

Once complete, select "Finish" and reboot your system.

After logging in again, check and confirm that the root filesystem mounted on / has been expanded:

df -h

The size of the root filesystem should be close to the size of your microSDHC card.

Filesystem      Size  Used Avail Use% Mounted on
/dev/root        15G  978M   13G   7% /

Next we are going to increase the swap space by editing the swap configuration file and restarting the service:

sudo nano /etc/dphys-swapfile

Modify the line for CONF_SWAPSIZE and set it to 1024 and save the file.

# set size to absolute value, leaving empty (default) then uses computed value
#   you most likely don't want this, unless you have an special disk situation

Restart the swapfile service:

sudo service dphys-swapfile restart

Network Configuration

Since this will be a full node, you will need to allow peer-to-peer network traffic through your router firewall. Every network configuration is different so this section is going to be more of a general guideline. Assuming you are connected to a router with DHCP enabled, your Raspberry Pi 2 should already have a local IP address, otherwise you will need to configure a static IP address. To show your current network configuration:

ifconfig eth0

eth0   Link encap:Ethernet  HWaddr b1:ff:4a:a4:ff:1b
       inet addr:  Bcast:  Mask:

inet addr is your local IP, HWaddr is your MAC address. In your router configuration, find the port forwarding settings and forward TCP/UDP traffic for port 7874 to the local IP address of your Raspberry Pi. I recommend setting up a DHCP static lease (aka DHCP reservation) to permanently associate the MAC with the local IP. This way the Raspberry Pi will always get the same local IP that you configured with the port fowarding rule.

Installing Java

Nxt requires Java 8. I recommend using Oracle Java for the best performance. For the Raspberry Pi, use the JDK version Linux ARM 32 Hard Float ABI, available for download here.

You can use the wget command in the console to directly download the file over HTTPS but you need to include a header to accept the Oracle license:

wget --no-check-certificate --no-cookies --header "Cookie: oraclelicense=accept-securebackup-cookie" http://download.oracle.com/otn-pub/java/jdk/8u131-b11/d54c1d3a095b4ff2b6607d096fa80163/jdk-8u131-linux-arm32-vfp-hflt.tar.gz

Extract the file, then rename and move the extracted directory to /usr/local/java:

tar xvzf jdk-8u131-linux-arm32-vfp-hflt.tar.gz
sudo mv jdk1.8.0_131/ /usr/local/java

Update your system to use Java at this location:

sudo update-alternatives --install "/usr/bin/java" "java" "/usr/local/java/bin/java" 1
sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/local/java/bin/javac" 1
sudo update-alternatives --set java /usr/local/java/bin/java
sudo update-alternatives --set javac /usr/local/java/bin/javac

Set the Java environment variables:

sudo nano /etc/profile

Add the following to the end of the file:

export JAVA_HOME
export JRE_HOME
export PATH

Reload /etc/profile and check the java version:

source /etc/profile
java -version

You should see an output similar to this:

java version "1.8.0_131"
Java(TM) SE Runtime Environment (build 1.8.0_131-b11)
Java HotSpot(TM) Client VM (build 25.131-b11, mixed mode)

When new versions of Oracle Java are released, you can simply extract them and overwrite the directory at /usr/local/java.

Installing Nxt

Download the latest version of Nxt from the public repository. You can use the wget again to download the file. As of this writing the current Nxt release is version is 1.11.5, but you will want to make sure you are using the latest version available.

wget https://bitbucket.org/JeanLucPicard/nxt/downloads/nxt-client-1.11.5.zip

Check the hash of the package and verify that it matches the hash in the signed release notes. You can also verify the hash in the blockchain. The Nxt account used by lead core developer Jean Luc is NXT-X4LF-9A4G-WN9Z-2R322.

sha256sum nxt-client-1.11.5.zip

facb359f2a4fae62b5e2cbb2f5a41bd8cface8090ba72d3ddcba22a904fb23d3  nxt-client-1.11.5.zip

Extract the archive to create the "nxt" directory:

unzip nxt-client-1.11.5.zip

Before configuring Nxt, you will need to find out your public IP address. You can do so with the following command:

curl ipinfo.io

Take note of your public IP address and then run the following command to create a new configuration file:

nano ~/nxt/conf/nxt.properties

The following is an example configuration file:


If you were able to configure port forwarding on your router, set nxt.myAddress to your public IP address shown in the output of the curl command, otherwise remove this line from the configuration file. For the other parameters, we've set the API to allow connections from everywhere. Once you have things working, you should consider restricting access to your local network or specific IP addresses. See nxt/conf/nxt-default.properties for descriptions of configuration parameters. Save the configuration file and exit the editor.

Edit the startup file and optimize the memory configuration:

nano ~/nxt/run.sh

Add the parameter -Xmx640m to increase the default the Java heap memory allocation to 640mb:

java -Xmx640m -cp classes:lib/*:conf nxt.Nxt

Blockchain Sync

You are now ready to start the server. Since this is a fresh installation, your node will need to download the entire blockchain to synchronize with the Nxt network. In some cases, this can take a very long time depending on the speed of your network connection and the type of memory card you are using.

You can speed things up significantly if you download a recent copy of the Nxt blockchain. The following blockchain download instructions are OPTIONAL. Use them only if you trust the source of the download and the source of the hashes used to verify the download. To download the blockchain from the Nxtportal Amazon S3 repository:

mkdir ~/nxt/nxt_db
wget https://s3.amazonaws.com/nxtblockchain/nxt_blockchain_1.10.3_1005300.zip

Verify the hash of the file matches the hash in the alias URI published on the blockchain:

sha256sum nxt_blockchain_1.10.3_1005300.zip

f7a1747ef6e5be9a71c1cd36dad8104b7dc7c83c8bdb346674e342cc11a9e28c  nxt_blockchain_1.10.3_1005300.zip

Extract the blockchain to the nxt_db directory:

unzip -d ~/nxt/nxt_db/ nxt_blockchain_1.10.3_1005300.zip

Startup & Connect

Nxt runs as a server process that provides an API and a web client interface. First, start the server:

cd ~/nxt

You should see the Nxt server start up and synchronize with the network. When startup is complete you will see the following:

2017-05-01 12:00:00 INFO: Nxt server 1.11.5 started successfully.
2017-05-01 12:00:00 INFO: Copyright © 2013-2016 The Nxt Core Developers.
2017-05-01 12:00:00 INFO: Copyright © 2016-2017 Jelurida IP B.V.
2017-05-01 12:00:00 INFO: Distributed under GPLv2, with ABSOLUTELY NO WARRANTY.
2017-05-01 12:00:00 INFO: Client UI is at https://localhost:7876/index.html

Open a web browser on a PC connected to the same network navigate to the local IP of the Raspberry Pi on port 7876.


For the interactive API interface, append /test to the url.


Congratulations, if you are able to access the login / test page your Nxt installation is successful. To stop the Nxt server, press CTRL-C at the console.

Final Steps

Secure client access

Before you can safely use Nxt, you should enable TLS on your node. If you use HTTP, a attacker on your network may be able to steal your passphrase. I highly recommend configuring a self-signed cert for your node and using HTTPS only.

Run the following to generate a keypair and self-signed certificate. It may take a minute depending on the keysize:

cd ~/nxt
keytool -genkeypair -keyalg RSA -keysize 2048 -validity 365 -keystore keystore

Once the keystore has been created, update the nxt.properties file to enable SSL:

nano ~/nxt/conf/nxt.properties

Add the following configuration parameters, filling in the password you entered when generating the keystore:

nxt.keyStorePassword=[YOUR KEYSTORE PASSWORD]

Restart your Nxt node. You should now be able to access the client over HTTPS. Note that if you are using a self-signed cert, your browser will prompt you with a number of warnings before loading the page.

Install screen

To make management of your node easier, I recommend installing screen. It will let you run programs in detachable sessions.

sudo apt-get install screen

To use screen on your Nxt server, create a startup script with the following commands:

echo "screen -mS nxt java -Xmx640m -cp classes:lib/*:conf nxt.Nxt" > ~/nxt/screen.sh
chmod +x ~/nxt/screen.sh

Now you can start the server using the following commands:

cd ~/nxt

You can detach from the screen session by pressing CTRL-A, D. To re-attach the session, enter the command:

screen -r nxt

Auto startup

An easy way automatically start the Nxt server at boot is with the cron task scheduler. You need to add an entry specifying @reboot and run your startup commands there:

crontab -e

@reboot sleep 30 && cd /home/pi/nxt && ./run.sh

In this example the Nxt server will startup on boot after a 30 second delay. You can use cron to schedule other tasks as well.

For questions or comments, please visit the forum thread for this blog post.