DOCSEARCHbyAlgolia
Submit Docs

RaspiBlitz Documentation

repository·dev·Indexed 25 days ago

https://github.com/raspiblitz/raspiblitz

A DIY Bitcoin and Lightning Fullnode solution designed for Raspberry Pi 4 or 5, with support for alternative platforms including amd64, Proxmox, Armbian, Ubuntu, and various virtual machine environments. Includes guides for hardware requirements, build script configuration, and data drive management for blockchain storage.

Tokens
10K
Snippets
23
Records
55
Agent score
82%

What's inside RaspiBlitz

  1. Overview of RaspiBlitz

    dev
    RaspiBlitz is a DIY Bitcoin and Lightning Fullnode solution designed to run on a Raspberry Pi 4 or 5. It features an optional display for easy setup and monitoring. The project is primarily intended for users who want to learn how to run decentralized nodes from home and participate in the open-source Bitcoin ecosystem. The core repository contains the bash and python scripts used to build the RaspiBlitz software.

  2. Minimum and recommended hardware requirements

    dev

    To run RaspiBlitz on alternative platforms, ensure your hardware meets these specifications:

    Minimum Requirements:

    • ARMv8 or x86 processor (64 bit)
    • 1 GB RAM
    • 500 GB HDD
    • Python >= 3.9

    Recommended Specs:

    • 2GB DDR3 ECC RAM (8GB+ if using ZFS)

    • USB 3.0 / SATA / PCIE / NVME connectors
    • SSD - multiple disks for redundancy

  3. RaspiBlitz Ecosystem Components

    dev

    RaspiBlitz is composed of several distinct repositories that handle different aspects of the node experience:

  4. Manage files in the development environment

    dev

    The development environment uses specific linking behaviors for the home.admin directory:

    • Automatic Linking: Files in home.admin on your host are linked to /home/admin inside the VM. These are linked automatically every time the VM boots.
    • Adding New Files: If you add a new file to home.admin, you must run vagrant provision to ensure it is linked inside the VM.
    • Assets Folder: The /home/admin/assets folder is currently NOT kept in sync. To access your development assets inside the VM, use the path /vagrant/home.admin/assets/.

  6. Configure Grafana InfluxDB Datasource

    dev

    To visualize RaspiBlitz metrics, add InfluxDB as a data source in Grafana:

    1. Go to Configuration (gear icon) > Data Sources > Add data source and select InfluxDB.
    2. Use the following settings:
      • HTTP URL: http://localhost:8086 (or your InfluxDB server IP)
      • Auth: Default settings
      • Database: raspiblitz
      • User: grafana
      • Password: [GRAFANA-PASSWORD]
      • HTTP Method: POST (recommended)
    3. Click Save & Test.

    Important: After saving, note the UID of the data source. You can find it in the browser URL when editing the data source (e.g., .../datasources/edit/<data_source_uid>). You will need this UID to import the RaspiBlitz dashboard.

  7. Verify a Debian base image using GPG and SHA512

    dev

    When manually preparing an amd64 image, you must verify the integrity and authenticity of the Debian base image using the provided SHA512SUMS and GPG signature.

    Verification Workflow:

    1. Download the .iso, SHA512SUMS, and SHA512SUMS.sign files.
    2. Import the Debian CD signing key via a keyserver.
    3. Verify the signature of the SHA512SUMS file using gpg.
    4. Use sha512sum to check the image file against the verified sums.
    # Download the base image:
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-11.3.0-amd64-netinst.iso
# Download the SHA512SUMS:
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/SHA512SUMS
# Download the Signature:
wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/SHA512SUMS.sign

# Verify:
# download the signing pubkey:
gpg --keyserver keyring.debian.org --receive-key DF9B9C49EAA9298432589D76DA87E80D6294BE9B

# Verify the signature of the SHA512SUMS file
gpg --verify SHA512SUMS.sign

# Compare the hash to the hash of the image file:
sha512sum -c SHA512SUMS --ignore-missing

  8. Run RaspiBlitz in a Virtual Machine

    dev

    You can run RaspiBlitz as a VM on a Linux host (tested with Debian/Ubuntu in VirtualBox, virt-manager, or cockpit-machines, and TrueNAS/bhyve).

    1. Create the base image

    Download and install a base OS on at least a 32GB drive. Debian is the most tested and closest to RaspberryOS. Ubuntu is also supported but less tested. For experimentation, you can use pre-made images from osboxes.org (password: osboxes.org).

    2. Building the Raspiblitz scripts

    Run the build script in the terminal of the base OS with sudo access:

    # download the build script
wget https://raw.githubusercontent.com/rootzoll/raspiblitz/dev/build_sdcard.sh

# run
sudo bash build_sdcard.sh -f false -b dev -d headless -t false -w off

    Build Script Options:

    • -EXPORT: Just print build parameters & exit
    • -h, --help: Show help info
    • -i, --interaction [0|1]: Interaction before proceeding (default: 1)
    • -f, --fatpack [0|1]: Fatpack mode (default: 1)
    • -u, --github-user [raspiblitz|other]: GitHub user to check (default: raspiblitz)
    • -b, --branch [v1.7|v1.8]: Branch to build (default: v1.10)
    • -d, --display [lcd|hdmi|headless]: Display class (default: lcd)
    • -t, --tweak-boot-drive [0|1]: Tweak boot drives (default: 1)
    • -w, --wifi-region [off|US|GB|other]: WiFi ISO code (default: US) or off

    3. Data Drive Configuration

    Attach a second virtual disk to serve as the BLOCKCHAIN drive. This keeps data portable and independent from the OS.

    • Tip: Create a raw image of 500+ GB for best compatibility. If you encounter permission issues, try symlinking the disk image to /var/lib/libvirt/images.

  9. Set up RaspiBlitz on an amd64 machine

    dev

    For amd64 Laptops, Desktops, or Servers, you can use an amd64 image.

    Requirements:

    • Connection to the internet via a LAN cable.
    • OS disk: Minimum 32GB SSD recommended. You can use an Endurance type SD card if the computer supports booting from SD, or a USB SSD (e.g., Sandisk Extreme Pro USB 128 GB). An Optical Drive Bay Caddy can be used to add a second SSD in laptops with optical drives.
    • Data disk: A new, minimum 1TB SSD is recommended to store data independently from the OS.

    To find download links or build locally, refer to the CI documentation in /ci/README.md.

  10. Manual amd64 image release process

    dev

    This guide outlines the manual process for creating a signed amd64 image release for RaspiBlitz. This is intended for maintainers or advanced users building custom images.

    High-Level Workflow:

    1. Base Setup: Boot Ubuntu Live and install a clean Debian base on an OS disk.
    2. Script Installation: Install RaspiBlitz scripts on the Debian system.
    3. Build: Run the build scripts to configure the environment.
    4. Image Creation: Use dd to clone the OS disk, compress it with gzip, and generate a sha256 hash.
    5. Signing: Use GPG to create a detached signature (--detach-sign --armor) of the hash file.
    6. Distribution: Upload the .img.gz, .sha256, and .asc files to a server.

  11. Configure a virtual data drive for RaspiBlitzVM

    dev

    To run the full setup process, you must attach a large virtual data drive (VDI) to the RaspiBlitzVM via the VirtualBox Manager GUI.

    1. Stop the VM: Use the off command inside the VM or run vagrant halt from your host.
    2. Open VirtualBox GUI: Select the RaspiBlitzVM and click change.
    3. Add Storage: In the mass storage section, add a second disc as primary slave to the existing controller.
    4. Select VDI: Use a torrent-downloaded VDI or create a new dynamic VDI of approximately 900GB. If local space is limited, store the VDI on an external drive.
    5. Restart: Run vagrant up and vagrant ssh to begin the setup process.