Sign in Subscribe
Bitcoin

Bitcoin Lightning node and wallet setup on Ubuntu.

Alan Sunny

Alan Sunny

— 12 min read
Bitcoin Lightning node and wallet setup on Ubuntu.
Bitcoin Lightning node

This guides go through setting up bitcoin lightning node and wallet on an Ubuntu linux machine.

Feel free to jump across the content with below links.

Preparing the environment

Updates

# Fetch the list of available updates, upgrade current
sudo apt update &&
sudo apt upgrade -y &&
sudo apt autoremove -y

Security

# Setup firewall
sudo ufw enable &&
sudo ufw allow from 127.0.0.1 to any &&

# Secure shared memory
echo "tmpfs /run/shm tmpfs defaults,noexec,nosuid 0 0" | sudo tee -a /etc/fstab

Edit /etc/sysctl.conf

sudo gedit /etc/sysctl.conf

Copy this, paste at the bottom and save.

Common dependencies

sudo apt install -y nodejs npm git &&

# Install global npm packages to ~/.npm-global (prevents permission headaches, see https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)
mkdir ~/.npm-global && npm config set prefix '~/.npm-global' &&
echo 'export PATH=~/.npm-global/bin:$PATH' | tee -a ~/.profile ~/.bashrc && source ~/.profile

PGP keyservers

At the time of writing, the default gpg keyservers appears to be unavailable. They can be changed to Ubuntu's keyservers with:

echo 'keyserver hkp://keyserver.ubuntu.com' | tee -a ~/.gnupg/gpg.conf

Developer signing keys

Add the public keys of the developers whose software we'll be using. This is required for later verifying their signatures.

Also interesting our guide to deploy Bitcoin on full node.

Please verify these keys first! Some places to start looking:
# Wladimir J. van der Laan (Bitcoin Core binary release signing key) <[email protected]>
gpg --recv-keys 01EA5486DE18A882D4C2684590C8019E36C2E964 &&

# Thomas Voegtlin (Electrum maintainer) <[email protected]>
gpg --recv-keys 6694D8DE7BE8EE5631BED9502BD5824B7F9470E6 &&

# Rusty Russell (Bitcoin Core contributor and c-lightning maintainer) <[email protected]>
gpg --recv-keys 15EE8D6CAB0E7F0CF999BFCBD9200E6CD1ADB8F1 &&

# Chris Belcher (Electrum Personal Server and JoinMarket maintainer) <[email protected]>
gpg --recv-keys 0A8B038F5E10CC2789BFCFFFEF734EA677F31129 &&

# Nadav Ivgi (Spark, Lightning Charge, Esplora) <[email protected]>
gpg --recv-keys FCF19B67866562F08A43AAD681F6104CD0F150FC &&

# Dan Janosik (btc-rpc-explorer maintainer) <[email protected]>
gpg --recv-keys F579929B39B119CC7B0BB71FB326ACF51F317B69

Tor

To install Tor as a system service:

sudo apt install -y tor

Tor will automatically start running as a background service.

To install the Tor Browser Bundle:

sudo apt install -y torbrowser-launcher && # Fix for https://bugs.python.org/issue20087, necessary for torbrowser-launcher < 0.3sudo update-locale LANG=en_US.UTF-8 && source /etc/default/locale

You can start the tor browser with torbrowser-launcher from the command line, or using the launcher (due to the locale bug, this only works after a logout & login)

We have also written an article on Git troubleshooting.

Bitcoin Core

Installing

# Create dir for installation files
mkdir -p ~/bitcoin-installation && cd ~/bitcoin-installation && rm -rf * &&

# Download binaries
wget https://bitcoincore.org/bin/bitcoin-core-0.17.1/bitcoin-0.17.1-x86_64-linux-gnu.tar.gz &&

# Download signature
wget https://bitcoincore.org/bin/bitcoin-core-0.17.1/SHA256SUMS.asc &&

# Verify signature - should see "Good signature from Wladimir J. van der Laan (Bitcoin Core binary release signing key) <[email protected]>"
gpg --verify SHA256SUMS.asc &&

# Verify the binary matches the signed hash in SHA256SUMS.asc - should see "bitcoin-0.17.1-x86_64-linux-gnu.tar.gz: OK"
grep bitcoin-0.17.1-x86_64-linux-gnu.tar.gz SHA256SUMS.asc | sha256sum -c - &&

# Unpack binaries
tar xvf bitcoin-0.17.1-x86_64-linux-gnu.tar.gz &&

# Install binaries system-wide (requires password)
sudo cp bitcoin-0.17.1/bin/* /usr/bin

Configuring

Create and edit bitcoin.conf

mkdir -p ~/.bitcoin &&gedit ~/.bitcoin/bitcoin.conf

Add the following and save:

server=1

# Connect via Tor, comment if you prefer to connect directly
proxy=127.0.0.1:9050

# No incoming connections (requires port forwarding or an hidden service)
nolisten=1

# For faster sync, set according to available memory. For example, with 8GB memory, something like dbcache=5000 might make sense. Check total memory with `free -m`.
# For reduced memory usage, this can be tuned down or removed once the initial sync is complete. The default is 300 (mb).
dbcache=1000

# Optional extended transaction index (takes more space, required for btc-rpc-explorer)
txindex=1

# Reduce storage requirements (won't work with btc-rpc-explorer)
# prune=50000 # ~6 months, 50GB

# Reduce bandwidth requirements (node won't show unconfirmed transactions)
# blocksonly=1

Also see jlopp's bitcoin core config generator.

Running

bitcoind

To test bitcoind is running:

bitcoin-cli getblockchaininfo
QuickNode - Blockchain API and Node Infrastructure | Ethereum, Solana, Polygon, BSC + More
Top projects & businesses trust QuickNode for fast, reliable Web3 infrastructure. Instantly access 12 chains across a global node network, plus tools and APIs to help you build & scale high-quality blockchain applications!
Ethereum, Solana, Polygon, BSC + More

btc-rpc-explorer

Installing

# Cleanup previous source code files (if any)
rm -rf ~/btc-rpc-explorer &&

# Download source
git clone https://github.com/janoside/btc-rpc-explorer ~/btc-rpc-explorer && cd ~/btc-rpc-explorer &&
git checkout 1ca6f54b93a56d942a90f3e0072265c9df3b9e6c &&

# Verify signature - should see "Good signature from Dan Janosik <[email protected]>"
git verify-commit HEAD &&

# Install user-wide
npm install -g

Configuring

Create and edit ~/.config/btc-rpc-explorer.env, add the following line to enable password protection:

BTCEXP_BASIC_AUTH_PASSWORD=mySecretPassword

Note: don't forget to change mySecretPassword to your own password. You can set the password to anything, it will be required to access the explorer.

Refer to the btc-rpc-explorer docs for the full list of options.

Running

btc-rpc-explorer

Then open http://localhost:3002/node-status and login with an empty username and your superSecretPassword.

Electrum Wallet

Click on the following link If you would like more information on Electrum wallet.

Installing

# Install dependencies
sudo apt install -y python3-setuptools python3-pyqt5 python3-pip &&

# Create dir for installation files
mkdir -p ~/electrum-installation && cd ~/electrum-installation && rm -rf * &&

# Download source
wget https://download.electrum.org/3.3.4/Electrum-3.3.4.tar.gz &&

# Download signature
wget https://download.electrum.org/3.3.4/Electrum-3.3.4.tar.gz.asc &&

# Verify signature - should see "Good signature from Thomas Voegtlin (https://electrum.org) <[email protected]>"
gpg --verify Electrum-3.3.4.tar.gz.asc Electrum-3.3.4.tar.gz &&

# Unpack
tar xvf Electrum-3.3.4.tar.gz && cd Electrum-3.3.4 &&

# Install dependencies
pip3 install .[fast] &&

# Install system-wide (requires sudo password)
sudo ./setup.py install

Configuring

# Connect to local EPS server only
electrum setconfig server 127.0.0.1:50002:s &&
electrum setconfig oneserver true

Running

Electrum can now be opened from the launcher or using the command line with electrum.

Note: You may now open Electrum and configure a wallet, but it won't connect to a server until EPS is configured (next step) and bitcoind is synced.

Electrum Personal Server

Installing

# Cleanup previous source code files (if any)
rm -rf ~/eps &&

# Download source
git clone https://github.com/chris-belcher/electrum-personal-server.git ~/eps && cd ~/eps &&

# Checkout v0.1.6 (latest stable)
git checkout eps-v0.1.6 &&

# Verify signature - should see 'Good signature from "Chris Belcher <[email protected]>"'
git verify-commit HEAD &&

# Install user-wide
pip3 install --user .

Configuring

Copy the sample configuration file as config.cfg and edit it:

cp ~/eps/config.cfg_sample ~/eps/config.cfg &&
gedit ~/eps/config.cfg

Find your Master Public Key in electrum wallet (Wallet > Information) and add it to config.cfg under [master-public-keys] as a new line with {wallet_name}={master_pubkey}. wallet_name can be anything. For example:

mywallet=zpub6rFR7y4Q2AijBEqTUquhVz398htDFrtymD9xYYfG1m4wAcvPhXNfE3EfH1r1ADqtfSdVCToUG868RvUUkgDKf31mGDtKsAYz2oz2AGutZYs

Save config.cfg

Running

electrum-personal-server ~/eps/config.cfg

When running for the first time, EPS will import the addresses and quit. You should start it again.

If you're importing an existing wallet with historical transactions, a rescan will be required: electrum-personal-server-rescan ~/eps/config.cfg

Note: Electrum Wallet will only connect to Electrum Personal Server once bitcoind is synced.

Take a break to sync

Now is a good time to sit back and wait for all the Bitcoin blocks to download before continuing to the Lightning part. It will take quite a while. You can follow the progress on the terminal with bitcoin-cli getblockchaininfo or with btc-rpc-explorer on http://localhost:3002/node-status

Meanwhile you may want to setup startup services for bitcoind, btc-rpc-explorer and eps and test a restart.

You may also continue to setting up remote access to btc-rpc-explorer and EPS from your local network, or from anywhere using Tor Hidden Services.

Once the sync is complete, Electrum wallet should connect to EPS (a green circle on the bottom-right) and we can continue to the Lightning part!

c-lightning

Installing

# Install dependencies
sudo apt install -y autoconf automake build-essential libtool libgmp-dev libsqlite3-dev net-tools zlib1g-dev &&

# Cleanup previous source code files (if any)
rm -rf ~/lightning &&

# Download source
(git clone https://github.com/ElementsProject/lightning ~/lightning || git -C ~/lightning fetch) &&

# Checkout latest stable
cd ~/lightning && git checkout v0.7.0 &&

# Verify signature - should see: Good signature from "Rusty Russell <[email protected]>"
git verify-tag v0.7.0 &&

# Build
./configure && make &&

# Install system-wide (requires sudo password)
sudo make install

Configuring

Create and edit ~/.lightning/config

mkdir -p ~/.lightning &&gedit ~/.lightning/config

Add the following and save:

# default network is testnet,"bitcoin" means mainnet
network=bitcoin

# connect via Tor, comment to connect directly
# might be wise to turn-off during initial sync
proxy=127.0.0.1:9050

# Peers won't be able to initiate the opening of new channels with this node (the node will initiate instead). To allow that, a static IP or a Tor hidden service must be configured.
autolisten=false

# uncomment to set your own (public) alias. By default a random one is chosen.
# for privacy reasons, it is recommended not to set a custom alias.
#alias=MyPublicNodeAlias

Running

lightningd --log-level=debug

To test c-lightning is running:

lightning-cli getinfo

Backup

There are two important files to backup:

~/.lightning/hsm_secret must be backed up once. ~/.lightning/lightningd.sqlite3 must be backed up regulary.

Instructions for setting up backups are available here, including optional encrypted cloud backups to Keybase.

Spark Wallet

Installing

# Create dir for installation files
mkdir -p ~/spark-installation && cd ~/spark-installation && rm -rf * &&

# Download npm package
wget https://github.com/shesek/spark-wallet/releases/download/v0.2.4/spark-wallet-0.2.4-npm.tgz &&

# Download signature
wget https://github.com/shesek/spark-wallet/releases/download/v0.2.4/SHA256SUMS.asc &&

# Verify signature - should show "Good signature from Nadav Ivgi <[email protected]>"
gpg --verify SHA256SUMS.asc &&

# Verify the downloaded binary matches the signed hash in SHA256SUMS.asc
grep spark-wallet-0.2.4-npm.tgz SHA256SUMS.asc | sha256sum -c - &&

# Install user-wide
npm install -g spark-wallet-0.2.4-npm.tgz

Configuring

The default configuration options should work out-of-the-box. You may set custom config options in ~/.spark-wallet/config.

To set custom login credentials instead of the randomly generated ones, add a line with login=myUsername:myPassword.

Refer to the spark docs for the full list of options.

Running

spark-wallet --pairing-url

Spark will automatically generate random credentials and save them to ~/.spark-wallet/cookie.

The --pairing-url option will print the pairing url, which includes your wallet access key. You can open this URL to access your wallet. It will look like that: http://localhost:9737/?access-key=[...].

You may also use --pairing-qr to print a qr with the pairing url (useful for mobile access).

Startup services

Note: If you already have the services running from the terminal, stop them before starting the systemd service.

Stage 1: Bitcoin, EPS, btc-rpc-explorer

# Download home-node repo
git clone https://github.com/bitembassy/home-node ~/home-node && cd ~/home-node &&

# Verify signature - should see "Good signature from Nadav Ivgi <[email protected]>"
git verify-commit HEAD &&

# Copy service init files
sudo cp init/{bitcoind,eps,btc-rpc-explorer}.service /etc/systemd/system/ &&

# Reload systemd, enable services, start them
sudo systemctl daemon-reload &&
sudo systemctl start bitcoind && sudo systemctl enable bitcoind &&
sudo systemctl start eps && sudo systemctl enable eps &&
sudo systemctl start btc-rpc-explorer && sudo systemctl enable btc-rpc-explorer

Stage 2: Lightning, Spark

# Copy service init files
sudo cp ~/home-node/init/{lightningd,spark-wallet}.service /etc/systemd/system/ &&

# Reload systemd, enable services, start them
sudo systemctl daemon-reload &&
sudo systemctl start lightningd && sudo systemctl enable lightningd &&
sudo systemctl start spark-wallet && sudo systemctl enable spark-wallet

Controlling services

  • Start: sudo systemctl start <name>
  • Restart: sudo systemctl restart <name>
  • Stop: sudo systemctl stop <name>
  • Status: sudo systemctl status <name>

The services names are: bitcoind,lightningd,btc-rpc-explorer,eps and spark-wallet

LAN access

To connect to EPS, Spark and btc-rpc-explorer over the local network you will need to configure the services to bind on 0.0.0.0 and add a firewall rule allowing local connections.

Configuring the services

  • To configure EPS: open ~/eps/config.cfg and under [electrum-server] change host=127.0.0.1 to host=0.0.0.0.
  • To configure Spark: open ~/.spark-wallet/config and add a new line with host=0.0.0.0.
  • To configure btc-rpc-explorer: open ~/.config/btc-rpc-explorer.env and add a new line with BTCEXP_HOST=0.0.0.0.

You can configure all three using the following commands:

Restart the services for the changes to take effect:

sudo systemctl restart eps && sudo systemctl restart spark-wallet && sudo systemctl restart btc-rpc-explorer

Firewall rules

You will need to add a firewall rule allowing access from your local network IP address range. For example, if your IP range is 192.168.1.x, run:

sudo ufw allow from 192.168.1.0/24 to any port 50002,3002,9737,22 proto tcp

The following script can be used to try and automatically detect your network IP range and add a matching firewall rule:

ips=($(ip -4 -o -f inet addr show | grep 'scope global dynamic' | tr -s ' ' | cut -d' ' -f4)) &&
if [ ${#ips[@]} -ne 1 ]; then echo "multiple networks found, cannot determine IP address"; \
else (set -x; sudo ufw allow from ${ips[0]} to any port 50002,3002,9737,22 proto tcp); fi
Note: You may want to define a Static DHCP Lease on your router for your node, so the IP won't change and local clients can find it.

SSH access (optional)

sudo apt install -y openssh-server &&

# disable root login, disable password auth
sudo sed -i 's/^PermitRootLogin .*/PermitRootLogin no/' /etc/ssh/sshd_config &&
sudo sed -i 's/^PasswordAuthentication .*/PasswordAuthentication no/' /etc/ssh/sshd_config &&
sudo service ssh reload

# TODO: set nonstandard SSH port? instructions for setting up keys?

To ensure SSH access availability, you may want to accept SSH connections from all sources with sudo ufw allow ssh. This is less secure than white-listing source IPs, but may be considered acceptable for the SSH daemon.

Tor Hidden Services

Edit /etc/tor/torrc, add:

HiddenServiceDir /var/lib/tor/hidden_service/
HiddenServiceVersion 3
HiddenServicePort 50002 127.0.0.1:50002
HiddenServicePort 3002 127.0.0.1:3002
HiddenServicePort 9737 127.0.0.1:9737
HiddenServicePort 9090 127.0.0.1:9090
HiddenServicePort 22 127.0.0.1:22

Then restart with: sudo service tor restart

To get your .onion hostname: sudo cat /var/lib/tor/hidden_service/hostname

To make Spark aware of its .onion address, edit ~/.spark-wallet/config and add a line with: public-url=http://[your-host-name].onion:9737/

This can be done automatically with: echo public-url=http://`sudo cat /var/lib/tor/hidden_service/hostname`:9737/ | tee -a ~/.spark-wallet/config

Your onion server exposes the following services:

  • Port 50002: Electrum Personal Server
  • Port 9737: Spark Wallet
  • Port 3002: btc-rpc-explorer
  • Port 9090: Cockpit
  • Port 22: SSH server

For example, to access btc-rpc-explorer, open [your-host-name].onion:3002 on any Tor Browser.

Updating software

You can update the installed software by re-running the installation scripts. You can copy the commands from this README, or fetch and run them from git using:

# Download home-node repo
git clone https://github.com/bitembassy/home-node ~/home-node && cd ~/home-node &&

# Verify signature - should see "Good signature from Nadav Ivgi <[email protected]>"
git verify-commit HEAD &&

# To update bitcoin core
./scripts/install-bitcoin.sh &&

# To update c-lightning
./scripts/install-clightning.sh &&

# To update electrum
./scripts/install-electrum.sh &&

# To update electrum personal server
./scripts/install-eps.sh &&

# To update spark wallet
./scripts/install-spark.sh &&

# To update btc-rpc-explorer
./scripts/install-btc-rpc-explorer.sh

Materials for this guide was taken from the following git repository sources:

GitHub - bitembassy/home-node: Instructions for setting up a Bitcoin+Lightning node on Ubuntu 18.04
Instructions for setting up a Bitcoin+Lightning node on Ubuntu 18.04 - GitHub - bitembassy/home-node: Instructions for setting up a Bitcoin+Lightning node on Ubuntu 18.04
GitHubbitembassy
GitHub - ElementsProject/lightning: c-lightning — a Lightning Network implementation in C
c-lightning — a Lightning Network implementation in C - GitHub - ElementsProject/lightning: c-lightning — a Lightning Network implementation in C
GitHubElementsProject

Read more