Bitcoin Knots Installation Guide for Umbrel

📌 This guide is specifically for Umbrel 0.5.4 and earlier versions
(Prior to the umbrelOS 1.0.0 upgrade)
⚠️ LND Compatibility Warning: For compatibility with LND, use Bitcoin Knots v27.1 instead of v28.x. Bitcoin Core/Knots v28+ has introduced changes that are not yet fully compatible with current LND versions.
⚠️ Important: This guide will help you upgrade from Bitcoin Core to Bitcoin Knots on Umbrel. Make sure to backup your wallet before proceeding.

Prerequisites

Installation Process

1Backup Your Wallet (Optional but Recommended)

First, create a backup of your wallet file for safety.

Backup wallet command 
cp ~/umbrel/app-data/bitcoin/data/bitcoin/wallet.dat ~/wallet.dat.backup-$(date +%Y%m%d)

2Create Build Directory

Create a directory for building the Bitcoin Knots Docker image.

Create directory commands 
mkdir -p ~/umbrel/bitcoin-knots-docker
cd ~/umbrel/bitcoin-knots-docker

3Create Dockerfile

Create a Dockerfile for Bitcoin Knots v27.1 (recommended for LND compatibility). This uses Ubuntu base to avoid compatibility issues.

Create Dockerfile command 
cat > Dockerfile << 'EOF'
FROM ubuntu:22.04

# Install necessary packages
RUN apt-get update && apt-get install -y \
    wget \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Create bitcoin user to match the lncm image
RUN useradd -r -u 1000 -s /bin/bash -m -d /data bitcoind

# Download and install Bitcoin Knots v27.1 (for LND compatibility)
RUN cd /tmp && \
    wget https://github.com/bitcoinknots/bitcoin/releases/download/v27.1.knots20240801/bitcoin-27.1.knots20240801-x86_64-linux-gnu.tar.gz && \
    tar -xzf bitcoin-27.1.knots20240801-x86_64-linux-gnu.tar.gz && \
    mv bitcoin-27.1.knots20240801/bin/* /usr/local/bin/ && \
    chmod +x /usr/local/bin/bitcoind /usr/local/bin/bitcoin-cli /usr/local/bin/bitcoin-tx && \
    rm -rf /tmp/bitcoin-27.1*

# Create data directory
RUN mkdir -p /data/.bitcoin && chown -R bitcoind:bitcoind /data

# Switch to bitcoind user
USER bitcoind
WORKDIR /data

# Set the same volumes as lncm image
VOLUME ["/data/.bitcoin/"]

# Use the same entrypoint
ENTRYPOINT ["bitcoind"]

# Use the same default command
CMD ["-zmqpubrawblock=tcp://0.0.0.0:28332", "-zmqpubrawtx=tcp://0.0.0.0:28333"]
EOF

4Build the Docker Image

Build the Bitcoin Knots Docker image. This may take a few minutes.

Build Docker image command 
sudo docker build -t bitcoind-knots:v27.1 .

5Backup Configuration Files

Create backups of the configuration files before modifying them.

Backup configuration commands 
cd ~/umbrel/app-data/bitcoin
cp docker-compose.yml docker-compose.yml.backup

cd ~/umbrel/app-data/bitcoin/data/bitcoin
cp bitcoin.conf bitcoin.conf.backup

6Update Docker Compose Configuration

Update the docker-compose.yml to use the Bitcoin Knots image.

Update docker-compose.yml command 
cd ~/umbrel/app-data/bitcoin
sed -i 's|image: lncm/bitcoind:v.*|image: bitcoind-knots:v27.1|' docker-compose.yml

7Fix RPC Configuration

Fix potential RPC binding conflicts in bitcoin.conf.

Fix RPC configuration command 
cd ~/umbrel/app-data/bitcoin/data/bitcoin
sed -i 's/^rpcbind=0\.0\.0\.0/#rpcbind=0.0.0.0/g' bitcoin.conf

8Restart Bitcoin

Stop and start Bitcoin with the new Knots image.

Restart Bitcoin commands 
cd ~/umbrel
sudo ./scripts/app stop bitcoin
sleep 10
sudo ./scripts/app start bitcoin

9Verify Installation

Check that Bitcoin Knots is running successfully.

Verification commands 
sleep 5
sudo docker exec bitcoin_bitcoind_1 bitcoin-cli --version
sudo docker exec bitcoin_bitcoind_1 bitcoin-cli getblockchaininfo

10After Installation: Reindex if Needed

If your blockchain data needs reindexing (common when switching versions), you might need to temporarily add reindex flag.

Add reindex flag (if needed) 
# Backup current docker-compose.yml
cd ~/umbrel/app-data/bitcoin
cp docker-compose.yml docker-compose.yml.backup-reindex

# Add reindex flag
sed -i 's/CMD \["-zmqpubrawblock/CMD \["-reindex", "-zmqpubrawblock/' docker-compose.yml

# Restart with reindex
cd ~/umbrel
sudo ./scripts/app restart bitcoin

# Monitor logs to check progress
sudo docker logs -f bitcoin_bitcoind_1
Remove reindex flag after completion 
# Wait for reindex to complete (check logs), then:
cd ~/umbrel/app-data/bitcoin
cp docker-compose.yml.backup-reindex docker-compose.yml

# Restart normally
cd ~/umbrel
sudo ./scripts/app restart bitcoin
✅ Success! You should now see "Bitcoin Knots version v27.1" in the output, confirming the installation was successful. After blockchain synchronization completes, restart your Lightning node to ensure compatibility.

Complete Installation Script

You can copy and run all commands at once using this complete script:

Complete installation script 
#!/bin/bash

# Backup wallet (optional but recommended)
cp ~/umbrel/app-data/bitcoin/data/bitcoin/wallet.dat ~/wallet.dat.backup-$(date +%Y%m%d)

# Create directory for Knots Docker build
mkdir -p ~/umbrel/bitcoin-knots-docker
cd ~/umbrel/bitcoin-knots-docker

# Create Dockerfile
cat > Dockerfile << 'EOF'
FROM ubuntu:22.04

# Install necessary packages
RUN apt-get update && apt-get install -y \
    wget \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Create bitcoin user to match the lncm image
RUN useradd -r -u 1000 -s /bin/bash -m -d /data bitcoind

# Download and install Bitcoin Knots v27.1 (for LND compatibility)
RUN cd /tmp && \
    wget https://github.com/bitcoinknots/bitcoin/releases/download/v27.1.knots20240801/bitcoin-27.1.knots20240801-x86_64-linux-gnu.tar.gz && \
    tar -xzf bitcoin-27.1.knots20240801-x86_64-linux-gnu.tar.gz && \
    mv bitcoin-27.1.knots20240801/bin/* /usr/local/bin/ && \
    chmod +x /usr/local/bin/bitcoind /usr/local/bin/bitcoin-cli /usr/local/bin/bitcoin-tx && \
    rm -rf /tmp/bitcoin-27.1*

# Create data directory
RUN mkdir -p /data/.bitcoin && chown -R bitcoind:bitcoind /data

# Switch to bitcoind user
USER bitcoind
WORKDIR /data

# Set the same volumes as lncm image
VOLUME ["/data/.bitcoin/"]

# Use the same entrypoint
ENTRYPOINT ["bitcoind"]

# Use the same default command
CMD ["-zmqpubrawblock=tcp://0.0.0.0:28332", "-zmqpubrawtx=tcp://0.0.0.0:28333"]
EOF

# Build the Bitcoin Knots image
sudo docker build -t bitcoind-knots:v27.1 .

# Backup the original docker-compose.yml
cd ~/umbrel/app-data/bitcoin
cp docker-compose.yml docker-compose.yml.backup

# Update the docker-compose.yml to use Knots image
sed -i 's|image: lncm/bitcoind:v.*|image: bitcoind-knots:v27.1|' docker-compose.yml

# Fix RPC binding conflict in bitcoin.conf
cd ~/umbrel/app-data/bitcoin/data/bitcoin
cp bitcoin.conf bitcoin.conf.backup
sed -i 's/^rpcbind=0\.0\.0\.0/#rpcbind=0.0.0.0/g' bitcoin.conf

# Restart Bitcoin with the new image
cd ~/umbrel
sudo ./scripts/app stop bitcoin
sleep 10
sudo ./scripts/app start bitcoin

# Verify it's running Bitcoin Knots
sleep 5
sudo docker exec bitcoin_bitcoind_1 bitcoin-cli --version

echo "Bitcoin Knots v27.1 installation complete!"

# After installation completes
echo "If reindexing is needed, use the following commands:"
echo "cd ~/umbrel/app-data/bitcoin"
echo "cp docker-compose.yml docker-compose.yml.backup-reindex"
echo "sed -i 's/CMD \\\\[\"-zmqpubrawblock/CMD \\\\[\"-reindex\", \"-zmqpubrawblock/' docker-compose.yml"
echo "cd ~/umbrel"
echo "sudo ./scripts/app restart bitcoin"

Reverting to Bitcoin Core

If you need to revert back to Bitcoin Core, use these commands:

Complete revert script 
#!/bin/bash

# Stop Bitcoin
cd ~/umbrel
sudo ./scripts/app stop bitcoin

# Restore original docker-compose.yml
cd ~/umbrel/app-data/bitcoin
cp docker-compose.yml.backup docker-compose.yml

# Restore original bitcoin.conf
cd ~/umbrel/app-data/bitcoin/data/bitcoin
cp bitcoin.conf.backup bitcoin.conf

# Start Bitcoin (will use original Core image)
cd ~/umbrel
sudo ./scripts/app start bitcoin

# Verify it's back to Bitcoin Core
sleep 5
sudo docker ps --format "table {{.Names}}\t{{.Image}}" | grep bitcoind
sudo docker exec bitcoin_bitcoind_1 bitcoin-cli --version

# Optional: Clean up Knots artifacts
sudo docker rmi bitcoind-knots:v27.1
rm -rf ~/umbrel/bitcoin-knots-docker

echo "Reverted to Bitcoin Core successfully!"

Version Compatibility

Note: The Bitcoin Knots version you select is important:

Important: Umbrel Version

This guide is designed for Umbrel 0.5.4 and earlier versions. If you have upgraded to umbrelOS 1.0.0 or later, the file paths and commands may be different. This guide specifically addresses the pre-1.0.0 Umbrel architecture.
Remember: Always backup your wallet.dat file before making major changes to your Bitcoin node!