Web app

ThunderHub is an open source LND node manager where you can manage and monitor your node on any device or browser. It allows you to take control of the lightning network with a simple and intuitive UX and the most up-to-date tech stack.

ThunderHub homepage

Preparations

Install dependencies

Install Node.js using the apk package manager.

These are build dependencies (safe to remove after installation, if you want)

$SU apk add --virtual .build-deps git gnupg npm

These are runtime dependencies

$SU apk add nodejs-current

Create the `thunderhub` user/group

$SU addgroup -S thunderhub

$SU adduser \
    -S \
    -D \
    -H \
    -h /dev/null \
    -s /sbin/nologin \
    -G thunderhub \
    -g thunderhub \
    thunderhub

Add `thunderhub` user to the `lnd` group

$SU adduser thunderhub lnd

Add `satoshi` user to the `thunderhub` group

$SU adduser satoshi thunderhub

Reverse proxy

In the Security section, we set up a reverse proxy. Now we can add the ThunderHub configuration.

Enable the reverse proxy to route external encrypted HTTPS traffic internally to the ThunderHub.

$SU $EDITOR /etc/caddy/sites/thunderhub.caddy

/etc/caddy/sites/thunderhub.caddy

:4002 {
        import tls
 
        handle_errors 497 {
                redir https://{host}:{port}{uri} 301
        }
 
        handle {
                reverse_proxy 127.0.0.1:3000
        }
}

Reload Caddy

$SU rc-service caddy reload

Firewall

Configure the firewall to allow incoming HTTPS requests

$SU $EDITOR /etc/awall/optional/thunderhub.json

/etc/awall/optional/thunderhub.json

{
  "description": "Allow ThunderHub SSL",
 
  "filter": [
    {
      "in": "internet",
      "out": "_fw",
      "service": { "proto": "tcp", "port": 4002 },
      "action": "accept",
      "conn-limit": { "count": 10, "interval": 60 }
    }
  ]
}

Enable it

$SU awall enable thunderhub
$SU awall activate

Installation

ThunderHub provides a lightweight and easy to use web interface to accomplish a great node management.

Download source code

We get the latest release of the ThunderHub source code and install it.

Download the source code for the latest ThunderHub release. You can check the release page to see if a newer release is available. Other releases might not have been properly tested with the rest of the Microbolt configuration, though.

cd /tmp

VERSION=0.13.31

git clone --branch v$VERSION https://github.com/apotdevin/thunderhub.git && cd thunderhub

Signature check

To avoid using bad source code, verify that the release has been properly signed by the main developer Anthony Potdevin.

wget -qO- https://github.com/apotdevin.gpg | gpg --import

git verify-commit v$VERSION

Install and build

Install all dependencies using the Node Package Manager (NPM).

npm ci

Installation can take some time. There might be a lot of confusing output, but if you see something similar to the following, the installation was successful:

⚠️

At 2024-09-01 there is at least 26 vulnerabilities not addressable without breaking changes

npm audit fix

output

26 vulnerabilities (1 low, 10 moderate, 15 high)

To address issues that do not require attention, run:
  npm audit fix

To address all issues (including breaking changes), run:
  npm audit fix --force

Run `npm audit` for details.

Improve your privacy by opt-out of Next.js telemetry

npx next telemetry disable

Make it a global permanent installation

npm run build

mkdir ./dist/bin

printf "%s\n" \
    "#!/bin/sh" \
    "npm_package_version='$VERSION' \\" \
    "node \$@ /var/lib/thunderhub/main" \
    > ./dist/bin/cli.sh

chmod +x ./dist/bin/cli.sh

Install backend and dependencies files

$SU mv -f /tmp/thunderhub/dist /var/lib/thunderhub
$SU cp -R node_modules /var/lib/thunderhub

Install frontend files

$SU mkdir -p /var/lib/thunderhub/src/client
$SU cp -R /tmp/thunderhub/src/client/public         /var/lib/thunderhub/src/client/public
$SU cp    /tmp/thunderhub/src/client/next.config.js /var/lib/thunderhub/src/client/next.config.js
$SU mv -f /tmp/thunderhub/src/client/.next          /var/lib/thunderhub/src/client/.next

$SU chown -R thunderhub:thunderhub /var/lib/thunderhub

$SU ln -s /var/lib/thunderhub /usr/lib/node_modules/thunderhub
$SU ln -s ../lib/node_modules/thunderhub/bin/cli.sh /usr/bin/thunderhub

Cleanup

cd
rm -rf /tmp/thunderhub
$SU apk del .build-deps

Configuration

Edit the configuration file

$SU $EDITOR /etc/thunderhub/thubConfig.yaml

/etc/thunderhub/thubConfig.yaml

masterPassword: 'PASSWORD' # Default password unless defined in account
accounts:
  - name: 'Microbolt'
    serverUrl: '127.0.0.1:10009'
    macaroonPath: '/var/lib/lnd/data/chain/bitcoin/mainnet/admin.macaroon'
    certificatePath: '/var/lib/lnd/tls.cert'
    password: '[E] ThunderHub password'

💡

Replace the [E] ThunderHub password to yours

Enable auto-healthchecks

/etc/thunderhub/thubConfig.yaml

masterPassword: 'PASSWORD' # Default password unless defined in account
accounts:
  - name: 'Microbolt'
    serverUrl: '127.0.0.1:10009'
    macaroonPath: '/var/lib/lnd/data/chain/bitcoin/mainnet/admin.macaroon'
    certificatePath: '/var/lib/lnd/tls.cert'
    password: '[E] ThunderHub password'
healthCheckPingEnabled: true

Auto-backups to Amboss

Keep in mind that if you stop ThunderHub, Amboss will interpret that your node is offline because the connection is established between ThunderHub <-> Amboss to send healthchecks pings

/etc/thunderhub/thubConfig.yaml

masterPassword: 'PASSWORD' # Default password unless defined in account
accounts:
  - name: 'Microbolt'
    serverUrl: '127.0.0.1:10009'
    macaroonPath: '/var/lib/lnd/data/chain/bitcoin/mainnet/admin.macaroon'
    certificatePath: '/var/lib/lnd/tls.cert'
    password: '[E] ThunderHub password'
backupsEnabled: true

These last optional features are not available for a testnet node

Remote access over Tor

Add the following lines in the section “location hidden services” in the torrc file.

$SU $EDITOR /etc/tor/torrc

/etc/tor/torrc

# Hidden Service Thunderhub
HiddenServiceDir /var/lib/tor/thunderhub/
HiddenServiceVersion 3
HiddenServicePoWDefensesEnabled 1
HiddenServicePort 443 127.0.0.1:3000

Reload Tor configuration and get your connection address.

$SU rc-service tor reload
$SU cat /var/lib/tor/thunderhub/hostname

output

abcdefg..............xyz.onion

You should now be able to connect to your Thunderhub remotely via Tor using your hostname

Autostart on boot

Now we’ll make sure our lightning node manager starts as a service on the computer so that it’s always running.

Create the ThunderHub init.d unit and copy/paste the following configuration. Save and exit.

$SU $EDITOR /etc/init.d/thunderhub

/etc/init.d/thunderhub

#!/sbin/openrc-run
 
: ${THUNDERHUB_CONFIGFILE:=/etc/thunderhub/thubConfig.yaml}
: ${THUNDERHUB_DATADIR:=/var/lib/thunderhub}
: ${THUNDERHUB_LOGDIR:=/var/log/thunderhub}
: ${THUNDERHUB_USER:=thunderhub}
: ${THUNDERHUB_GROUP:=thunderhub}
: ${THUNDERHUB_BIN:=/usr/bin/thunderhub}
: ${THUNDERHUB_OPTS=${THUNDERHUB_OPTS}}
: ${THUNDERHUB_SIGTERM_TIMEOUT:=600}
 
THUNDERHUB_PIDDIR="/run/thunderhub"
 
name="ThunderHub"
description="Monitor and manage your node from any browser and any device"
 
directory="${THUNDERHUB_DATADIR}"
required_files="${THUNDERHUB_CONFIGFILE}"
pidfile="${THUNDERHUB_PIDDIR}/${SVCNAME}.pid"
retry="${THUNDERHUB_SIGTERM_TIMEOUT}"
 
command="${THUNDERHUB_BIN}"
command_args="${THUNDERHUB_OPTS}"
command_user="${THUNDERHUB_USER}:${THUNDERHUB_GROUP}"
command_background="true"
 
start_stop_daemon_args="--env BASE_PATH=''
                        --env COOKIE_PATH=''
                        --env ACCOUNT_CONFIG_PATH='${THUNDERHUB_CONFIGFILE}'
                        --env NODE_ENV='production'
                        --env NEXT_TELEMETRY_DISABLED=1
                        --stdout ${THUNDERHUB_LOGDIR}/debug.log
                        --stderr ${THUNDERHUB_LOGDIR}/debug.log"
 
depend() {
    need lnd tor
}
 
start_pre() {
    checkpath --file      --mode 0660 --owner "${command_user}" "${THUNDERHUB_CONFIGFILE}"
    checkpath --directory --mode 0750 --owner "${command_user}" "${THUNDERHUB_DATADIR}"
    checkpath --directory --mode 0755 --owner "${command_user}" "${THUNDERHUB_LOGDIR}"
    checkpath --directory --mode 0755 --owner "${command_user}" "${THUNDERHUB_PIDDIR}"
    checkconfig
}
 
checkconfig() {
    if ! grep -qs '^    macaroonPath: ' "${THUNDERHUB_CONFIGFILE}"
    then
        eerror ""
        eerror "ERROR: You must set a macaroonPath path to run ThunderHub"
        eerror "The setting must appear in ${THUNDERHUB_CONFIGFILE}"
        eerror ""
        return 1
    fi
}
 
stop() {
    ebegin "Stopping ${SVCNAME}"
    pkill -TERM -P "$(cat ${pidfile})"
    start-stop-daemon \
        --stop \
        --pidfile="${pidfile}" \
        --retry="${THUNDERHUB_SIGTERM_TIMEOUT}" \
        --exec="${THUNDERHUB_BIN}"
    eend $?
}

Enable execution permission

$SU chmod +x /etc/init.d/thunderhub

Enable logrotate

Enter the complete next configuration. Save and exit

$SU $EDITOR /etc/logrotate.d/thunderhub

/etc/logrotate.d/thunderhub

/var/log/thunderhub/*.log {
    weekly
    missingok
    rotate 104
    compress
    delaycompress
    notifempty
    create 0640 thunderhub thunderhub
    sharedscripts
    postrotate
        killall -HUP `cat /run/thunderhub/thunderhub.pid`
    endscript
}

Test

$SU logrotate /etc/logrotate.d/thunderhub --debug

Enable and start BTC RPC Explorer

$SU rc-update add thunderhub

$SU rc-service thunderhub start

🎉

Congratulations! You now have Thunderhub up and running

Check the log to see Thunderhub output. Exit with Ctrl-C

tail -f /var/log/thunderhub/debug.log

You can now access ThunderHub from within your local network by browsing to https://nakamoto01:4002, https://nakamoto01.local:4002 (or your equivalent ip address).

Access to your Amboss node account

In the “Home” screen - “Quick Actions” section, click on the Amboss icon “Login”, wait for the top right corner notification to show you “Logged in” and click again on the Amboss icon “Go to”. This will open a secondary tab in your browser to access your Amboss account node

⚠️

If you can’t do “Login”, maybe the cause is that you don’t have a public channel opened yet. You’ll need at least one public channel that has been open for a few days. Planning to open a public small-size channel to be connected with some Lightning Network peers or directly to the Amboss node. More info on Amboss docs

Making sure we are connected to the Amboss account, now back to Thunderhub for the next steps

Enable auto backups and healthcheck notifications to Amboss account

Open the “Settings” by pressing the cogwheel in the top right corner of the Thunderhub
Switch to “Yes” -> Amboss: “Auto backups” and “Healthcheck Pings”
Test pushing a backup to Amboss by entering in the “Tools” section, to the left main menu
Press to “Push” button to test the correct working
Go back to Amboss website and access “Account” in the main menu
Access to “Backup” and ensure that the last date of the backup is the same as before done. It is recommended to download the backup file and store it in a safe place for future recovers. The backup file will be updated automatically in Amboss for every channel opening and closing. You could do this too in the “Tools” section in Thunderhub, “Backups” -> “Backup all channels” -> “Download” button.
In Amboss, access “Monitoring” to configure “Healthcheck Settings”.

Feel free to link to Telegram bot notifications, enable different notifications, complete your public node profile in Amboss, and other things in the different sections of your account.

Recovering channels using the ThunderHub method

After possible data corruption of your LND node, ensure that this old node is completely off before starting the recovery. Once you have synced the new node, on-chain recovered with seeds, full on-chain re-scan complete, and Thunderhub installed and running, go to the Thunderhub dashboard.

From the left sidebar, click on “Tools”, and go to the “Backups” section -> “Recover Funds from Channels” -> push the “Recover” button.
Enter the complete string text of your previously downloaded channels backup file in the step before and push the “Recover” button. All of the channels that you had opened in your old node will be forced closed and they will appear in the “Pending” tab in the “Channels” section until closings are confirmed

⚠️

Use this guide as a last resort if you have lost access to your node or are unable to start LND due to a fatal error. This guide will close all your channels. Your funds will become available on-chain at varying speeds.

For the future: ThunderHub update

Follow again Web app page replacing the environment variable VERSION=x.xx value for the latest if it has not been already changed in this guide.

Update the ThunderHub configuration if necessary (see release notes)

$SU $EDITOR /etc/thunderhub/thubConfig.yaml

Restart the service to apply the changes

$SU rc-service thunderhub restart

Channel backup Mobile app

Web app

Preparations

Install dependencies

Create the thunderhub user/group

Add thunderhub user to the lnd group

Add satoshi user to the thunderhub group

Reverse proxy

Firewall

Installation

Download source code

Signature check

Install and build

Cleanup

Configuration

Autostart on boot

Enable logrotate

Enable and start BTC RPC Explorer

For the future: ThunderHub update

Create the `thunderhub` user/group

Add `thunderhub` user to the `lnd` group

Add `satoshi` user to the `thunderhub` group