Post
Topic
Board Beginners & Help
Merits 48 from 4 users
Topic OP
Complete Installation [GUIDE] of Lightning Desktop Nodes
by
Satofan44
on 09/05/2025, 18:13:56 UTC
⭐ Merited by LoyceV (42) ,Mahiyammahi (2) ,Halab (2) ,joker_josue (2)
I have gotten inspired from trying to participate in NotATether's Lightning challenge, and decided to undertake on a massive project here. I am well aware that there are various guides online, documentation and everything but as my experience trying to set up lightning shows, they have issues. Sometimes information is lacking, sometimes they have errors or outdated instructions, and other times they come with different assumptions of user knowledge which are implicit and not warranted or helpful.

My focus will be on desktop wallets, as mobile wallets usually do not require guides or require minimum setup. If you have issues with a mobile application, contact the developers of it. It is likely related to your specific device and OS version configuration.

This is an experimental break-down of every wallet that I have attempted to install. The introduction is written ahead of time, and at the time of writing I do not know how many wallets I will attempt or how many days it will take me to publish a partial version of this thread. The guide will also focus on providing information for a single operating system using up to date information. If someone else wants to repeat this process for your own OS, you are very welcome to contribute with that information. If you have suggestions or feedback, feel free to post them here or DM me directly.  Smiley

Important Reminders
  • This is an installation guide, using the software to open channels and make transactions is not part of this.
  • Some attempts might not work out, as was the case with my first try using Eclair. But that doesn’t make the guide less valuable, failure is an integral part of this journey. As we figure things out, I’ll update the guide accordingly. There will also be a FAQ section which is very much needed. My personal experience is that sometimes looking up information regarding errors results with no useful information.
  • At times basic Linux knowledge is required and expected. If you're new to Linux, make sure you're comfortable with tasks like navigating directories, using the terminal, and more. If you're not sure, check out a guide such as this one: https://www.geeksforgeeks.org/30-days-of-linux/. For those that have a GUI, you will have an easier time just using it for basic operations instead of the commands but you are welcome to try and learn.



Part 1: Overview and shared Prerequisites

The list of LN wallets that are part of this guide:

Operating System: Ubuntu 24.04 LTS, desktop or server.

To limit duplication of information, a short-guide for Bitcoin Core will be provided in this section. For each wallet it will be mentioned individually if this is a prerequisite.

Bitcoin Core Setup:
1. Download the latest release from here: https://bitcoincore.org/en/download/. At the time of writing this was v29.0. In most situations where Ubuntu is usually used, you will require the file that is linked as Linux (tgz). Note: If you want to do additional verification on the download, the instructions for several operating systems are found on the same link. I will not reproduce them here. I will work in the /home/ folder but you can work in any location of your preference. Open a terminal and run the following commands, which are always shown in code blocks:
Code:
cd /home/
wget https://bitcoincore.org/bin/bitcoin-core-29.0/bitcoin-29.0-x86_64-linux-gnu.tar.gz
2. Extract the contents of the file to a location of your choosing. It can be on the desktop but anywhere else that you are comfortable with. Actually, you can just copy the extract bitcoind and bitcoin-cli to your target location and ignore the remainign files.
Code:
tar -xvf bitcoin-29.0-x86_64-linux-gnu.tar.gz
cp /home/bitcoin-29.0/bin/bitcoin-cli /home/bitcoin-cli
cp /home/bitcoin-29.0/bin/bitcoind /home/bitcoind
3. The default data directory is /root/.bitcoin, and to keep things simple we will also use this location. You can change this by specifying --datadir if you want. In this step, we create the directory, the bitcoin.conf files and specify the needed configurations. I will use nano as the text editor as it is more user friendly.  
Code:
mkdir /root/.bitcoin
nano /root/.bitcoin/bitcoin.conf
Use the following configuration options and make sure to specify your own RPC username and password.
Quote
daemon=1
server=1
txindex=1
wallet=firstwallet
rpcuser=yourusername
rpcpassword=yourpassword

zmqpubrawblock=tcp://127.0.0.1:29000
zmqpubhashblock=tcp://127.0.0.1:29000
zmqpubrawtx=tcp://127.0.0.1:29001
Information about each option used here is provided in the FAQ. Please read the 3rd post of this thread. Note: You will need 750 GB or more disk space to run a full node.

4. If you have done everything correctly the following things will be done: First start bitcoind, and give it a few seconds of time to run properly. Then use bitcoin-cli to create a new wallet called wallet.
Code:
/home/bitcoind
/home/bitcoin-cli createwallet firstwallet
To confirm you have done this successfully, you will receive a response like this:
Quote
{
  "name": "firstwallet"
}
Next, a shutdown of the software is done using the -cli and it is started again using the bitcoind. Note: as some system configurations can be slow, always give bitcoind a few seconds of time before running the next command in any code block. If you run commands too fast after startup you will receive a error.
Code:
/home/bitcoin-cli stop
/home/bitcoind
While this step was not entirely necessary as Bitcoin Core will automatically load the created wallet in the current instance, it is provided so that the configuration file can be tested. You want to make sure that your wallet will load when you restart the software as well. To check the currently loaded wallets after doing a restart, use the following command:
Code:
/home/bitcoin-cli listwallets
Again, if you get this response that means you have completed the steps correctly.
Quote
{
  "name": "firstwallet"
}
5. The final step is to fully synchronize the blockchain. You can check the status of your node with the following command:
Code:
/home/bitcoin-cli getblockchaininfo
You will receive a response like this:
Quote
{
  "chain": "main",
  "blocks": 219242,
  "headers": 895831,
  "bestblockhash": "0000000000000012767dba93bdb63e4a3e0df576e3a2e8439a78c813feb3d792",
  "bits": "1a05a6b1",
  "target": "00000000000005a6b10000000000000000000000000000000000000000000000",
  "difficulty": 2968775.332075074,
  "time": 1359805720,
  "mediantime": 1359804704,
 "verificationprogress": 0.01017237324622422,
  "initialblockdownload": true,

  "chainwork": "000000000000000000000000000000000000000000000028fe60976baa91803d",
  "size_on_disk": 6124750373,
  "pruned": false,
  "warnings": [
  ]
}
If you see something like this, that means you have successfully completed all steps so far. Congratulations!  Smiley The blocks line tells you how many blocks you have synchronized, and the headers tells you the current block number of the Bitcoin blockchain. Alternatively, you can also follow the progress with verificationprogress which needs to reach 0.99 or wait until initialblockdownload is set to false. It is important to remember that synchronization time is not proportional, so if it took you 4 hours to reach 25% of the blocks that does not mean that it will take you just 12 more hours to reach full synchronization.

At this point, I strongly suggest that you take a break and let it synchronize. You have deserved it.



Part 2: Eclair
Prerequisites: Bitcoin Core and Adoptium OpenJDK.

Adoptium OpenJDK Setup:
1. In the first step, download the Adoptium JDK from Github: https://github.com/adoptium/temurin21-binaries/releases. Then extract it and move it to /root/opt. The version at the time of writing this guide is 21.0.7+6, so you may need to adjust the wget command if there is a newer version of it is explicitly required by Eclair. This information was sourced from this guide, which I followed to successfully install Adoptium on my own systems. You can consult it if more steps are needed by your configuration.
Code:
wget https://github.com/adoptium/temurin21-binaries/releases/download/jdk-21.0.7%2B6/OpenJDK21U-jdk_x64_linux_hotspot_21.0.7_6.tar.gz
tar -xvf OpenJDK21U-jdk_x64_linux_hotspot_21.*.tar.gz
sudo mv jdk-21.0.7+6 /opt/
2. Export the environment variables by editing .bashrc. You need to add the following two quoted lines at the end of the .bashrc file using nano.
Quote
export JAVA_HOME=/opt/jdk-21.0.7+6
export PATH=$PATH:$JAVA_HOME/bin

Code:
nano ~/.bashrc
3. Next, force an update on .bashrc with the source command and verify the installation:
Code:
source ~/.bashrc
echo $JAVA_HOME
You should get a response like this:
Quote
/opt/jdk-21.0.7+6
4. Set the default JAVA version:
Code:
sudo update-alternatives --install /usr/bin/java java /opt/jdk-21.0.7+6/bin/java 1
sudo update-alternatives --config java
Quote
You will get a response similar to this depending on your system:

There is 1 choice for the alternative java (providing /usr/bin/java).

  Selection    Path                        Priority   Status
------------------------------------------------------------
* 0            /opt/jdk-21.0.7+6/bin/java   1         auto mode
  1            /opt/jdk-21.0.7+6/bin/java   1         manual mode

Press <enter> to keep the current choice
  • , or type selection number:
If you have multiple versions of java, select this one as the default by entering the right number. In this case select 0. With this, the prerequisites are complete and you can start the Eclair installation process.


Eclair Setup:
1. Download the latest version of eclair-node and extract the files to a separate folder. At the time of writing this is Eclair v0.12.0 and we will again use a folder located in /home.
Code:
cd /home/
wget https://github.com/ACINQ/eclair/releases/download/v0.12.0/eclair-node-0.12.0-4df8cd0-bin.zip
apt install uzip
unzip eclair-node*.zip
2. Next, create .eclair in the root directory similar to what was required for Bitcoin Core and create a configuration file named eclair.conf. The options in bold are those which you need to edit. Make sure that your API password is strong, and that the RPC configuration data matches that which you have set up in bitcoin.conf.
Code:
mkdir /root/.eclair/
nano /root/.eclair/eclair.conf

Quote
eclair.node-alias=alias
eclair.server.port=9735
eclair.api.enabled=true
eclair.api.port=8080
eclair.api.password=Password
eclair.bitcoind.rpcuser=YourUsernameFromBitcoin.Conf
eclair.bitcoind.rpcpassword=YourPasswordFromBitcoin.Conf
eclair.bitcoind.zmqblock="tcp://127.0.0.1:29000"
eclair.bitcoind.zmqtx="tcp://127.0.0.1:29001"
eclair.bitcoind.wallet=firstwallet
This is a minimum working configuration. Many more configurations and examples can be found here: https://github.com/ACINQ/eclair/blob/master/docs/Configure.md.

3. Next, test that the node can be started. You will see no output, which is good. The test is to just make sure if no errors are thrown. You can exit by pressing CTRL + C.
Code:
/home/eclair-node-0.12.0-4df8cd0-bin/bin/eclair-node.sh

4. To enable the node to run in the background, a system service needs to be created. To do this, a systemd file must be created using the following nano command:
Code:
sudo nano /lib/systemd/system/eclair.service
Copy the following block inside eclair.service:
Quote
[Unit]
Description=Eclair Shell Script

[Service]
ExecStart=/home/eclair-node-0.12.0-4df8cd0/bin/eclair-node.sh

[Install]
WantedBy=multi-user.target
Afterwards, run the following commands to reload the daemon, enable the service and start it.
Code:
sudo systemctl daemon-reload
sudo systemctl enable eclair.service
systemctl start eclair.service

5. If you've done everything correctly so far, the eclair node should be runnign by now. To confirm this, run the following command:
Code:
/home/eclair-node-0.12.0-4df8cd0/bin/eclair-cli getinfo
You will need to enter your Eclair API password, the one you set up in the file eclair.conf. You will get an output similar to this one, which confirms that your node is successfully running.
Quote
{
  "version": "0.12.0-4df8cd0",
  "nodeId": "hidden",
  "alias": "helloLightning",
  "color": "#49daaa",
  "features": {
    "activated": {
      "option_simple_close": "optional",
      "option_route_blinding": "optional",
      "option_dual_fund": "optional",
      "gossip_queries_ex": "optional",
      "option_data_loss_protect": "mandatory",
      "var_onion_optin": "mandatory",
      "option_static_remotekey": "mandatory",
      "option_scid_alias": "optional",
      "option_onion_messages": "optional",
      "option_support_large_channel": "optional",
      "option_anchors_zero_fee_htlc_tx": "optional",
      "payment_secret": "mandatory",
      "option_shutdown_anysegwit": "optional",
      "option_channel_type": "optional",
      "basic_mpp": "optional",
      "gossip_queries": "optional",
      "option_quiesce": "optional",
      "option_payment_metadata": "optional"
    },
    "unknown": []
  },
  "chainHash": "6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000",
  "network": "mainnet",
  "blockHeight": 895432,
  "publicAddresses": [],
  "instanceId": "hidden"
}

For more information, visit the official Eclair documentation: https://github.com/ACINQ/eclair/tree/master/docs, https://github.com/ACINQ/eclair/blob/master/docs/Guides.md, https://github.com/ACINQ/eclair/blob/master/docs/FAQ.md.



Part 3: LND
Prerequisites: Bitcoin Core.

1. Download the latest version of LND and extract the files to a separate folder. At the time of writing this is lnd v0.18.5-beta and we will again use a folder located in /home. If you want to do additional verification on binaries, information is provided directly in the release. As you have already learned how to extract files in previous parts of this guide, multiple operations will be done in this step. Following the information from the documentation, we will move the binaries to a location where the system can find it.
Code:
cd home
wget https://github.com/lightningnetwork/lnd/releases/download/v0.18.5-beta/lnd-linux-amd64-v0.18.5-beta.tar.gz
tar -xvf lnd-linux-amd64-v0.18.5-beta.tar.gz
mv lnd-linux-amd64-v0.18.5-beta/lnd /usr/local/bin
mv lnd-linux-amd64-v0.18.5-beta/lncli /usr/local/bin

2. Before starting LND, a configuration file must be provided. To do this, the .lnd folder must be created in /root/ and a basic configuration must be set in the file lnd.conf. Make sure that your RPC username and password match the ones that you have set up for Bitcoin Core. The configuration only includes the basic necessary configurations and a few recommended lines from the documentation. Please read up on them if you are interested in what they do.
Code:
mkdir /root/.lnd
nano /root/.lnd/lnd.conf
Quote
bitcoin.node=bitcoind
bitcoind.rpcuser=YourUsernameFromBitcoin.Conf
bitcoind.rpcpass=YourPasswordFromBitcoin.Conf
bitcoind.zmqpubrawblock=tcp://127.0.0.1:29000
bitcoind.zmqpubrawtx=tcp://127.0.0.1:29001
bitcoin.mainnet=true

rpcmiddleware.enable=true
db.bolt.auto-compact=true
alias=ChooseNodeName

3. If you have done everything correctly, LND can be started simply by writing lnd in the console. However, first we will create a systemctl service using the provided sample file.
Code:
sudo nano /lib/systemd/system/lnd.service
Copy the following block inside lnd.service:
Quote
[Unit]
Description=Lightning Network Daemon

[Service]
ExecStart=/usr/local/bin/lnd
ExecStop=/usr/local/bin/lncli stop

[Install]
WantedBy=multi-user.target
Afterwards, run the following commands to reload the daemon, enable the service and start it.
Code:
sudo systemctl daemon-reload
sudo systemctl enable lnd.service
systemctl start lnd.service

4. The final step involves creating a wallet, after which you will be able to use lncli. Set a strong password of your choosing, a passphrase is optional, and make sure to back up the 24 words.
Code:
lncli createwallet

5. Verify that LND is running correctly using the getinfo command. Keep in mind that you may need to unlock your wallet first with lncli unlock.
Code:
lncli getinfo
You will get a response like this, I have removed some lines from it to keep it shorter:
Quote
{
    "version":  "0.18.5-beta commit=v0.18.5-beta",
    "commit_hash":  "4ccf4fc24c750d098cf24566ef4bbc0311c7d476",
    "identity_pubkey":  "03da538f07b1bafd88dbee79349ea567f391fc22c4aa65aa6772c880f7d94b2a4e",
    "alias":  "helloLightning",
    "color":  "#3399ff",
    "num_pending_channels":  0,
    "num_active_channels":  0,
    "num_inactive_channels":  0,
    "num_peers":  0,
    "block_height":  895990,
    "block_hash":  "0000000000000000000099c27e6d08fa06abad3b04ceabdc34806511d17987e0",
    "best_header_timestamp":  "1746812177",
    "synced_to_chain":  false,
    "synced_to_graph":  false,
    "testnet":  false,
    "chains":  [
        {
            "chain":  "bitcoin",
            "network":  "mainnet"
        }
    ],
Congratulations. You are now ready to use LND. Please refer to this guide for more information: https://docs.lightning.engineering/lightning-network-tools/lnd/first-steps-with-lnd.



Part 4: c-lightning
Prerequisites: Bitcoin Core.
Coming soon.



Final Note: There are of course improvements that can be made to the guide. I will do this, but only after I have tested that it works and if I think it is beginner friendly. It is very difficult to write such a big thread from scratch, so I'd rather make many revisions and improvements afterwards to minimize errors.