Cardano Node Installation

 

The following guide is written with instructions to be executed as a super user (“sudo”). You will be a target for hackers, and your ADA will be at risk. We strongly encourage you to implement any and all restrictions available to you to protect your server from unauthorized access. These enhancements however, are beyond the scope of this guide, and are entirely up to you to implement.

Hire a professional, unless you are willing to accept the entire burden of this project.


These instructions are tested & verified on version 1.30.1


Before you begin:

The following example is based on the following (officially recommended) specs:

  • Ubuntu 20.04 LTS x86_64 environment,

  • 4 CPUs (2 cores minimum),

  • 16 GB RAM (4 GB minimum memory),

  • 10 GB hard drive space PLUS the blockchain size (currently ~23 GB).

    • The ADA blockchain grows over time, so you should provide enough free space to accommodate that eventual growth (40gb is currently sufficient).

The Cardano software is constantly being updated, in phased implementations called “eras”. As these new phases are rolled out, this article will become obsolete. Please notify Support if this article is stale.

As new Eras come live, the hardware demands will also increase. The recommendations provided above will only satisfy the current Era’s needs.


Prepare Ubuntu.

Start at the terminal prompt; login to your host (assumed: non-root sudo user).

  • the host used here (the node IP) is required below (assembling the CAS parameters).

Update Ubuntu:

1 sudo apt update && sudo apt -y dist-upgrade

Set local node variables:

1 2 3 echo 'export NODE_HOME="$HOME/cardano"' >> $HOME/.bashrc echo 'export CARDANO_NODE_SOCKET_PATH="$NODE_HOME/node.socket"' >> $HOME/.bashrc source $HOME/.bashrc
  • These variables tell the software where the configuration and database files are located.


Download and install the Cardano software.

The cardano-wallet package also contains a functional node & CLI client. Install the 3 necessary binary (executable) files to a path folder.

Using the website, navigate to this page:

https://github.com/input-output-hk/cardano-wallet/releases/latest

Locate the latest feature release:

Scroll to the bottom of the page, download it, and un-tar it manually:

  • decompress these 3 binaries to the /usr/local/bin folder:

    • cardano-node

    • cardano-cli

    • cardano-wallet

Or, do it all from the command line:

1 2 3 4 5 6 7 8 9 10 VER_URL=$(curl https://github.com/input-output-hk/cardano-wallet/releases/latest | grep -e "href=" | cut -f2 -d'"') WALLET_VER=$(echo "$VER_URL" | awk -F "/" '{print $NF}') WALLET_TAR="cardano-wallet-$WALLET_VER-linux64.tar.gz" WALLET_URL="https://github.com/input-output-hk/cardano-wallet/releases/download/$WALLET_VER/$WALLET_TAR" WALLET_DIR="$(echo $WALLET_TAR | awk -F "." '{print $1}')" wget $WALLET_URL tar xzf "$WALLET_TAR" sudo cp "$WALLET_DIR/cardano-node" "/usr/local/bin/cardano-node" sudo cp "$WALLET_DIR/cardano-cli" "/usr/local/bin/cardano-cli" sudo cp "$WALLET_DIR/cardano-wallet" "/usr/local/bin/cardano-wallet"
  • NOTE: this method may become obsolete without warning. If you see a bunch of errors, just please notify us that this article is stale, and do it manually (as described above: using the website).

  • The tarball will be decompressed into the /usr/local/bin folder - which is already on your path. The configuration files and database will be stored in your home folder (cardano subdirectory).


Install the matching configuration files:

1 2 3 4 5 6 7 mkdir $NODE_HOME BUILD_VER="7654130" wget https://hydra.iohk.io/build/$BUILD_VER/download/1/mainnet-config.json -P "$NODE_HOME" wget https://hydra.iohk.io/build/$BUILD_VER/download/1/mainnet-topology.json -P "$NODE_HOME" wget https://hydra.iohk.io/build/$BUILD_VER/download/1/mainnet-byron-genesis.json -P "$NODE_HOME" wget https://hydra.iohk.io/build/$BUILD_VER/download/1/mainnet-shelley-genesis.json -P "$NODE_HOME" wget https://hydra.iohk.io/build/$BUILD_VER/download/1/mainnet-alonzo-genesis.json -P "$NODE_HOME"
  • The listed build ( “7654130” ) config files have been used for this article.

  • Newer builds may be required, but this installation worked with this build.

    • Newer builds may not work better (or at all). Use newer only if these listed files are obsolete.

    • For current info, navigate to: https://github.com/input-output-hk/cardano-node

    • Look for:

      • follow the link & download the latest files (or determine the latest build from the URL).


Finally, start the node & walk away for awhile.

TIP: Use either “screen” or “tmux” to keep the node alive in the event you’re disconnected.

1 cardano-node run --database-path "$NODE_HOME/state" --config "$NODE_HOME/mainnet-config.json" --topology "$NODE_HOME/mainnet-topology.json" --socket-path "$CARDANO_NODE_SOCKET_PATH"
  • Many hours (if not days) will pass as the blockchain synchronizes. Grab some coffee; go see a movie.

  • This delay is currently unavoidable.

  • Messages will begin scrolling by; this is normal. If anything is wrong, the node will stop itself.

Identify the synchronization state at anytime using this command:

1 cardano-cli query tip --mainnet

That should return something similar to this, indicating the node’s current “tip”:

Navigate to https://explorer.cardano.org/en and search for the epoch. That will reveal the date of the block currently being verified by your node, and give you some idea of your node’s progress. The progress slows as newer (busier) blocks are processed. If no progress occurs over the course of an hour, and the tip remains exactly the same - you may be stuck at an “Era boundary”. You’ll need to download the newest version of Cardano and restart the process. If you’re already using the latest version - then you should research the problem on a Cardano forum. Please notify GB Support of the issue, but please understand that we’ll be less helpful than the forum. We’re not Cardano, we didn’t write the software, and GB can’t fix their problems (and software under development always has problems).


Setup a secure tunnel for encrypted communication.

Your CAS server and this node must have a secure line. Your passphrase and other sensitive information will be passed back & forth. Encrypt (and protect) this communication by using a secure tunnel.

The GB Wallet Tunnel is recommended:

General Bytes has incorporated an open-source ssh client into CAS.

Click here for instructions to install the GB Wallet Tunnel Server.

  • Perfect for the GB Cloud CAS.

NOTE: to create a secure SSH tunnel (instead of the GB Wallet Tunnel) between your CAS server and your node, use:

ssh -f -N -i /path/to/your/key -l <LOGIN_ID> -L 8090:127.0.0.1:8090 <NODE_IP>

  • This method is unusable with the GB Cloud, and provided for those Operators with a Standalone CAS that wish to use “standard” stock OS tools.


Start the wallet HTTP server.

This is the piece that CAS actually “talks” to. The wallet server depends on a functional node, so all the previous work was done just to get to this point. Thank you for your patience.

At this point, you should have a secure connection from CAS to your node (as accomplished in the previous step). When you start the cardano-wallet using the parameters supplied below, port 8090 (default) will be exposed only to localhost (127.0.0.1).

The wallet will NOT work with CAS until the local blockchain has fully synchronized.

1 cardano-wallet serve --mainnet --port 8090 --node-socket $CARDANO_NODE_SOCKET_PATH --database $NODE_HOME/wallet
  • The port specified here (8090) is required below (assembling the CAS parameters).

Test it using this command:

1 curl http://localhost:8090/v2/network/information
  • Should return something like this (if started successfully):


Create a new wallet.

Cardano wallets (like all wallets) should be backed up using a recovery phrase. Cardano forces the issue, requiring you to build your wallet from a recovery phrase.

  • This step requires an active wallet server (previous step).

Create a 24-word (256-bit entropy) recovery phrase:

1 cardano-wallet recovery-phrase generate

Backup the recovery phrase NOW, before the phone rings, or the fire alarm sounds.

Use that recovery phrase to generate a new wallet:

1 cardano-wallet wallet create from-recovery-phrase GBDemo
  • You’ll be prompted to enter the recovery phrase generated above.

  • Use the second factor (if desired) or skip it.

  • Replace “GBDemo” with anything relevant to your instance.

  • Enter a 10+ character passphrase (important: save it),

    • this passphrase is required below (assembling the CAS parameters: wallet_passphrase).

Wallet details will be listed if creation is successful.

  • Locate the “id” - you’ll need that below (assembling the CAS parameters: wallet_id).

  • If you need to list it again (for any reason), use:

  • 1 cardano-wallet wallet list

Verify the wallet state:

1 cardano-wallet network information
  • The wallet is ready to use when the node tip catches up to the network tip ("status": "ready").

Wait for the node to fully synchronize!

  • When the status reaches ““, the node should be online & ready to use with CAS.

  • CAS Hot Wallet tests will fail until this point is reached.


Assemble the parameters for CAS:

Required: protocol : host : port : wallet_id : passphrase

The protocol is always: http

The host is the IP address of the Cardano node, the public-facing IP of the server.

  • When using an SSH tunnel (NOT the GB Wallet Tunnel), the host is: 127.0.0.1

The port is determined during wallet installation. Default = 8090

The wallet_id and wallet_passphrase is generated while creating a wallet.

Example parameter string (using the GB Wallet Tunnel):

http:34.73.196.201:8090:f8b60e7cccaa92cedc60be2e68a1d5c9fb172863:Passphrase

1. Create a new Crypto Setting for ADA (Cardano).

2. Insert the parameter string into the appropriate (Parameters) field:

3. Save it!


Test it:

Re-enter the Crypto setting and run the Hot Wallet Buy test.

  • Green means good!


More information (external links):

API documentation: https://input-output-hk.github.io/cardano-wallet/api/edge/

Cardano Github space : https://github.com/input-output-hk/cardano-node

Official build instructions: https://docs.cardano.org/projects/cardano-node/en/latest/getting-started/install.html

Cardano wallet-cli commands: https://github.com/input-output-hk/cardano-wallet/wiki/Wallet-command-line-interface

Official cardano-cli docs: https://docs.cardano.org/projects/cardano-node/en/latest/getting-started/cli.html

Official cardano-node docs: https://docs.cardano.org/projects/cardano-node/en/latest/reference/cardano-node-cli-reference.html

Parts of this article were mined from CoinCashew, which provided excellent (accurate) instructions to compile the source: https://www.coincashew.com/coins/overview-ada/guide-how-to-build-a-haskell-stakepool-node