DOCSEARCHbyAlgolia
Submit Docs

RaspiBlitz Documentation

website·Indexed 34 days ago

https://docs.raspiblitz.org

An open-source DIY platform for running a Bitcoin full node and Lightning Network node (LND and/or Core Lightning) on Raspberry Pi 4 and 5. The documentation covers hardware setup, software installation via SD card images, storage migration, SSH menu management, and Web UI usage.

Tokens
20.8K
Snippets
71
Records
185
Agent score
61%

What's inside RaspiBlitz

  1. Overview of RaspiBlitz features

    RaspiBlitz is an MIT-licensed open-source project that enables users to run a full Bitcoin node (to verify the blockchain and transactions) and a Lightning Network node (for fast, low-cost transactions) on a Raspberry Pi. It also supports the installation of additional apps and services directly on the node.

  2. Overview of RaspiBlitz storage migration scenarios

    Storage migration allows moving RaspiBlitz data and blockchain to a larger drive without reinstalling the node from scratch. This requires RaspiBlitz v1.12 (or higher) and is supported on Raspberry Pi 4 and 5. Supported migration paths include:

    1. SATA-USB SSD → larger SATA-USB SSD (Pi 4 or Pi 5)
    2. SATA-USB SSD → larger NVMe (Pi 5)
    3. NVMe → larger NVMe (Pi 5)

  3. Overview of RaspiBlitz Lightning Node

    RaspiBlitz is a do-it-yourself Bitcoin Lightning Node that runs a Bitcoin Fullnode alongside Lightning Network implementations (LND and/or Core Lightning) on a Raspberry Pi. It is designed for decentralized home operation and typically utilizes a 2TB NVMe drive and a dedicated display for monitoring and setup.

  4. Interoperability between LND and CLN

    LND and CLN nodes are interoperable because both follow the BOLT specification. They can open channels to each other and route payments. On a RaspiBlitz system, both implementations can run in parallel and even maintain channels between each other. However, there are currently no tools to convert a node's database from LND to CLN (or vice versa); channels must be closed to move funds between different implementations.

  5. Execute the RaspiBlitz workshop agenda

    Follow this structured flow for the workshop session:

    1. Welcome and Intro (10 min): Introduction to the Lightning Network, RaspiBlitz documentation, and GitHub.
    2. Assembling: Step-by-step hardware assembly guided by example pictures/slides.
    3. Basic Setup:
      • Ensure laptops are on the same local network as the nodes.
      • Guide participants through the WebUI setup for Bitcoin and LND.
      • Provide paper/pens for recording passwords and seeds.
    4. Syncing/Waiting Period (~30 min):
      • While LND scans and the blockchain finishes syncing, conduct an educational segment on Bitcoin/Lightning.
      • Demo funding and channel creation using a pre-prepared 'clean setup' node.
      • Troubleshooting: If sync is slow, check if Tor is blocked by the local network and consider syncing via clearnet. If a node fails to sync in time, shut it down via SSH (CTRL+C then shutdown now); it will resume at the user's home.

  6. Connect external wallet apps to RaspiBlitz

    You can connect various wallet applications to your RaspiBlitz node via the SSH menu. Supported apps include:

    • Zeus: Android & iOS
    • Zap: iOS
    • Bitbanana: Android
    • Fully Noded: iOS
    • Alby: Desktop

  7. Install and use Electrum Rust Server (Electrs)

    The Electrum Rust Server (Electrs) allows users to run their own Bitcoin indexer on RaspiBlitz. This enables fast queries for wallet balances and transaction history using any Electrum-protocol compatible wallet (like the Electrum wallet) without relying on third-party servers, thereby preserving privacy. After installation, an ELECTRS option appears in the SSH main menu.

  8. Issue TLS certificates using Let's Encrypt (acme.sh)

    RaspiBlitz includes acme.sh (installed in /home/admin/.acme.sh/) to create trusted TLS certificates. Certificates are stored on the external hard disk at /mnt/hdd/app-data/letsencrypt. Let's Encrypt does not issue certificates for IP addresses; a DNS domain or FQDN is required.

  9. Generate a system debug report

    Generate a filtered debug report to share with the community for troubleshooting. Private information like IPs and node IDs are filtered, but manual review is recommended before sharing.
    # Via SSH terminal (CTRL+C from menu)
# Generate report
debug

# Generate report with a link
debug -l

  10. Free up disk space by deleting indices

    If disk space is low, you can remove specific high-consumption indices via the SSH menu:

    • DELETE-ELEC: Deletes the Electrum index.
    • DELETE-INDEX: Deletes the Bitcoin Transaction Index (TX-Index).

  12. Perform emergency recovery of lost CLN channel states

    If channel states are lost, you can perform an emergency recovery. This requires restoring the hsm_secret (on-chain wallet keys) first, then uploading and applying an emergency.recover file.
    # 1. Upload the emergency.recover file via scp
scp hsm_secret emergency.recover admin@RASPIBLITZ_IP:~/

# 2. Copy it to the bitcoin user directory
sudo cp /home/admin/emergency.recover /home/bitcoin/.lightning/bitcoin/
sudo chown bitcoin:bitcoin /home/bitcoin/.lightning/bitcoin/emergency.recover

# 3. Run the recovery command
lightning-cli emergencyrecover

# 4. Verify recovered funds and peers
lightning-cli listfunds
lightning-cli listpeers

# List funding txids to check in a block explorer
lightning-cli listfunds | jq -r '.channels[] | .funding_txid'