Note: This document was written in July 2018. Lightning is new and improving fast. If you find any out-of-date information or omissions, please leave a comment.

Lightning is an intriguing new technology that promises (lightning) fast transactions at a scale that is unheard of for Bitcoin. And now that Lightning is live on the Bitcoin mainnet, it is also a potential money maker.

Unfortunately, I’ve also found that Lightning is extremely hard to install, and I’ve wasted many hours setting up a node. I’m sharing my experiences so others will hopefully have a smoother experience.

This blogpost only describes the installation process, and assumes the reader is proficient in setting up a server. To learn more about Lightning itself, check the excellent white paper. To learn more about the economics behind Lightning, see The Economics of Lightning Network Fees. LnRoute lists many helpful resources. Warning: Lightning is not for the faint of heart. There are known and unknown issues. The wallet’s private key will be stored on the Lightning node, and the node will have to be online 24/7 to route transactions. As always with crypto, do not experiment with more btc than you’re prepared to lose. (Or experiment on Testnet. But where’s the fun in that?).

Prerequisites

In the cloud on a Virtual Private Server (VPS), or on your own hardware. This tutorial shows how to install Lightning on a Digital Ocean VPS. I am considering installing and documenting Lightning on a ODROID-HC1 (leave a comment if you’re interested).

This tutorial assumes you’re using a Mac to connect to the VPS. Using Linux or Windows shouldn’t be too different though. Your Lightning node has to be always online to forward payments.

If you want to run a Lightning Network Node hassle-free, check these Lightning network and Bitcoin node providers.

Setup Digital Ocean

Setting up a VPS on Digital Ocean will take about 30 minutes to complete.

Create an account Create a new droplet Create SSH key pair Log in

Use the following referral link to create an account on Digital Ocean and receive $10 (I will receive $25).

Create a new droplet

On the Create Droplet page, select the One-click apps tab and the Docker option, and select the 320GB option on the same page.

Next, we’re going to create a new SSH key pair by entering the following command in the Terminal:

# 1. Create SSH key pair. "lightning" will be the filename

# Enter a passphrase to secure the file

$ ssh-keygen -f ~/.ssh/lightning -t rsa -b 4096

# 2. Backup lightning and lightning.pub files

$ cd ~/.ssh

$ (Make a safe backup) # 3. Copy the public key to the clipboard

$ pbcopy < ~/.ssh/lightning.pub

Back in the browser, click on the New SSH Key button and paste the public key (copied to the clipboard in step 3 above) into the text box, and click the Create button to create the droplet.

Once the droplet is created, copy the ip-address of the droplet.

# Log in.

$ ssh root@<droplet's ip-address> -i ~/.ssh/lightning

Install bitcoind

Lightning requires a locally running full bitcoin node (that will change in the future with the Neutrino light client). This step will download the full Bitcoin blockchain and will take about 12 to 24 hours to complete.

I followed the steps in Doug von Kohorn’s Lightning post.

Make sure to be logged in on your server. Install Bitcoind Docker image. Download the Bitcoin blockchain. Create a convenience script for easy access to the bitcoind container Wait while the blockchain is downloading.

Log in if you’re not logged in already.

# Log in.

$ ssh root@<droplet's ip-address> -i ~/.ssh/lightning

Create a bitcoind Docker container using the dockerfile which is (confusingly) located in a repo called lightning-node.

Bitcoind will save the blockchain and all settings on the disk, not in the container itself. This way, all data will persist, even if we replace the bitcoind container with an updated version.

# 1. Clone the bitcoind repo. (don't let the lightning

# node project name fool you, this will install bitcoind)

$ git clone https://github.com/dougvk/lightning-node.git # 2. Build the bitcoind Docker container.

$ cd lightning-node

$ docker build . -t dougvk/bitcoind # 3. Create a working directory outside of the Docker image,

# so the working directory won't be overwritten when you

# update the Docker image with a new bitcoind version.

$ mkdir -p /scratch/bitcoin/mainnet/bitcoind # 4. Run bitcoind and start downloading the blockchain.

$ docker run --name bitcoind -d -v /scratch/bitcoin/mainnet/bitcoind:/data -p 8333:8333 -p 9735:9735 dougvk/bitcoind:latest

Add a convenience script to access the bitcoind container:

# 1. Create script.

$ touch /bin/bitcoin-cli # 2. Make script executable.

$ chmod +x /bin/bitcoin-cli # 3. Edit script (See below).

$ nano /bin/bitcoin-cli # 4. Confirm script is working. This command shows the wallet info.

$ bitcoin-cli getwalletinfo

In Nano (step 3 above), edit the bitcoin-cli script as follows:

#!/usr/bin/env bash

docker run --rm --network container:bitcoind -v /scratch/bitcoin/mainnet/bitcoind:/data dougvk/bitcoind:latest bitcoin-cli "$@"

At the time of writing, the Bitcoin blockchain is 175GB in size. The blockchain download should already be in progress and will take up to 24 hours to complete. Take a break, a nap or a short vacation while the blockchain is downloading.

Check the status of the download by entering the following command. When the download is complete, the latest downloaded block should have today’s date.

# Check the blockchain download progress.

$ docker logs bitcoind --tail "10"

Install C-Lightning

Next, install the Lightning client. There are multiple Lightning implementations, such as C-Lightning and lnd. It shouldn’t matter which implementation you use, as all implementations should be interoperable.

I found this step more complicated than I expected and wasted time trying to use the lnd implementation. In the end I gave up on lnd and switched to C-Lightning. (Since the software and documentation is updated on an almost daily basis, it is entirely possible that lnd will be easier to install by the time you read this.) Installing C-Lightning should take about 30 minutes.

Make sure to be logged in on your server. Create a C-Lightning docker image and sync the Lightning network. Create a convenience script for easy access to the bitcoind container. Set name and other options

Log in if you’re not logged in already.

# Log in.

$ ssh root@<droplet's ip-address> -i ~/.ssh/lightning

Create the C-Lighting docker image and a scratch directory on disk so the data will persist even if we replace the lightning docker container.

# 1. Create a working directory outside of the Docker image,

# so the working directory won't be overwritten when you

# update the Docker image with a newer C Lightning version.

$ mkdir -p /scratch/bitcoin/mainnet/clightning # 2. Create the Lighting docker image.

$ docker run --rm --name lightning --network container:bitcoind -v /scratch/bitcoin/mainnet/bitcoind:/root/.bitcoin -v /scratch/bitcoin/mainnet/clightning:/root/.lightning --entrypoint /usr/bin/lightningd elementsproject/lightningd --network=bitcoin --log-level=debug

The Lightining node should now be downloading the Lightning network, which should take about 10 minutes.

Since the last command doesn’t return to the command prompt, open a new Terminal window or tab and log in again.

# Log in.

$ ssh root@<droplet's ip-address> -i ~/.ssh/<filename>

Next, we’ll create a convenience script to access the Lightning client.

# 1. Create script.

$ touch /bin/lightning-cli # 2. Make script executable.

$ chmod +x /bin/lightning-cli # 3. Edit script (See below).

$ nano /bin/lightning-cli # 4. Confirm script is working.

$ lightning-cli getinfo

In Nano (step 3 above), edit the lightning-cli script as follows:

#!/usr/bin/env bash

docker run --rm -v /scratch/bitcoin/mainnet/clightning:/root/.lightning --entrypoint /usr/bin/lightning-cli elementsproject/lightningd "$@"

I haven’t found the complete documentation of all config file options. If you’ve found one, please leave a comment. A basic config file sets the name of the Lightning node and the color the name appears in Lightning explorers, such as Recksplorer.

# 1. Create config file

$ touch /scratch/bitcoin/mainnet/clightning/config # 2. Edit and save config file (see below)

$ nano /scratch/bitcoin/mainnet/clightning/config

My config file is as follows. I’ve named my node Punchbeef✅ (yes, a Mystery Science Theater 3000 reference) and set its color to orange. The color is used various Lightning explorers and provides an way to stand out.You obviously want to change the alias and the color (unless you like orange). To ensure more stable channels, Chang Li of FirstBlock suggested to add bind-addr and announce-addr to the config file. However, bind-addr didn’t seem to work as expected.

alias=Punchbeef✅ # Change the alias, obviously

rgb=FF4500

#bind-addr=0.0.0.0:9735 This doesn't seem to work yet

announce-addr=<droplet's ip-address>:9735

Restart the Lightning node to the update the changes.

# 1. Stop the Lightning node

$ lightning-cli stop # 2. Start the Lightning node

# Note: this creates a new container. How do we restart

# the existing one? Any Docker experts here?

$ docker run --rm --name lightning --network container:bitcoind_mainnet -v /scratch/bitcoin/mainnet/bitcoind:/root/.bitcoin -v /scratch/bitcoin/mainnet/clightning:/root/.lightning --entrypoint /usr/bin/lightningd elementsproject/lightningd --network=bitcoin --log-level=debug

We now have a fully functional Lightning node running on mainnet.

Note: If you prefer to use lnd over C-Lightning, the undocumented command to install lnd on mainnet is as follows. For support, check their active Slack.

# Don't use unless you want to install LND, instead of C-Lightning! $ docker create --name=lnd lightninglabs/lnd --bitcoin.active --bitcoin.mainnet

Setting fees

The way to make money on the Lightning network is to forward transactions from other nodes via your node. The sending node will choose the optimal path, based on the fees nodes have set. So we want to set the fees to a price that’s low enough so that traffic will flow through our node, yet high enough to make a profit. That at least is the theory.

I was expecting to be able to set fees to optimize for more traffic. Unfortunately, I haven’t found a way to do that yet and am currently using the default settings. If anyone knows the solution or has suggestions, please leave a comment.

Connecting to nodes and creating Channels

Note: If you’re not familiar with the concept of Lightning channels, please see the original Lightning white paper or this introduction to Lightning.

Funding channels is a two step process: you first send btc from your current wallet to the node’s wallet, and then you fund the channel with btc from the node’s wallet. Creating and funding channels will take about two hours and will involve the following steps:

Create a Bitcoin address for the node’s wallet. Send btc to the address created in step 1 and wait for six confirmations. Connect to any Lightning node of your choosing to create a channel. Fund the channel with btc from step 2 and wait for six confirmations.

As with any other Bitcoin wallet, you can create multiple addresses for a single wallet. Send a small amount of btc to the Lightning wallet, like so:

# 1. Create new address.

$ lightning-cli newaddr

# confirmations. Check status at:

# https://www.blockchain.com/btc/tx/ # 2. Send btc to the address generated above and wait for six# confirmations. Check status at: # 3. Confirm the funds have been received.

$ lightning-cli listfunds

When needed, use the dev-listaddrs command to list all addresses of your Lightning wallet:

# List all addresses of your Lightning wallet.

$ lightning-cli dev-listaddrs

Next, connect to one or more other Lightning nodes.

# 1. Connect to another Lightning node. The parameters are

# the Lightning id, and optional ip-address and port.

# The command below connects to the author's Punchbeef✅ node.

$ lightning-cli connect 02060d0c8577cfc2a1962220a1cde4f623ca55ef80bd25e4be5a8b15fed78b11a3@178.62.237.239 # 2. Confirm your node is connected to the node in step 4, and

# the state is "GOSSIPING".

$ lightning-cli listpeers

I funded most channels with 318 kSatoshi (approx. 20 USD). Some hosts required a higher minimum, to which I conformed. I also checked the prices of the goods the merchants sold and made sure the channel had enough satoshi for a purchase of at least the cheaper items in the store.

Funding a channel is a channel is an on-chain event and needs to be confirmed.

# 1. If needed, list connections. Unfunded channels will have

# state set to 'GOSSIPING'

$ lightning-cli listpeers # 2. Fund the channel to peer ID 02060... belonging to Punchbeef✅

# with 400 kSat .

$ lightning-cli fundchannel 02060d0c8577cfc2a1962220a1cde4f623ca55ef80bd25e4be5a8b15fed78b11a3 400000

And boom. We’re live.

Payments

To test Lightning payments, you could buy a sticker or T-shirt at various merchants, but you can also buy an inbound channel from the Y’alls node for about $4.62. Why not? Browse to the about page of the Y’alls site and follow the steps below.