🛠️ Setup

Setup

Requirements

  • NPM installed
  • Node installed (Version 18 or higher)

Config

You can define some environment variables that ThunderHub can start with. To do this create a .env.local file in the root directory with the following parameters:

Notice - If you use the .env template file and don't want it to be replaced after an update please duplicate and rename to .env.local

# -----------
# Server Configs
# -----------
LOG_LEVEL = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly' # Default: 'info'
TOR_PROXY_SERVER='socks://127.0.0.1:9050' # Default: ''
 
# -----------
# Interface Configs
# -----------
THEME = 'dark' | 'light' | 'night' # Default: 'dark'
CURRENCY = 'sat' | 'btc' | 'fiat' # Default: 'sat'
 
# -----------
# Privacy Configs
# -----------
FETCH_PRICES = true | false # Default: true
FETCH_FEES = true | false # Default: true
DISABLE_LINKS = true | false # Default: false
DISABLE_LNMARKETS = true | false # Default: false
NO_VERSION_CHECK = true | false # Default: false

TOR Requests

ThunderHub connects to different external services for example to fetch BOS scores, BTC/fiat prices and BTC blockchain fees. Normally they are done through clearnet but you can configure a TOR proxy server so that they are all proxied through TOR.

You need to add the following parameter into your .env file with your TOR endpoint:

TOR_PROXY_SERVER='socks://your.tor.endpoint' # i.e. 'socks://127.0.0.1:9050'

SSO Account

You can define an account to work with SSO cookie authentication by adding the following parameters in the .env file:

# -----------
# SSO Account Configs
# -----------
COOKIE_PATH = '/path/to/cookie/file/.cookie' # i.e. '/data/.cookie'
SSO_SERVER_URL = 'url and port to node' # i.e. '127.0.0.1:10009'
SSO_CERT_PATH = '/path/to/tls/certificate' # i.e. '\lnd\alice\tls.cert'
SSO_MACAROON_PATH = '/path/to/macaroon/folder' # i.e. '\lnd\alice\data\chain\bitcoin\regtest\'
LOGOUT_URL = 'http://LogoutToThisUrl.com' # If not set it will logout to "/login"

To login to this account you must add the cookie file content to the end of your ThunderHub url. For example:

http://localhost:3000/sso?token=[COOKIE]

Replace [COOKIE] with the contents of the .cookie file.

SSO Account without authentication

You can DANGEROUSLY remove SSO authentication. This is useful for example if you plan on running ThunderHub only on your local network or through TOR.

DO NOT enable this option if your ThunderHub instance is available on the internet or your funds will probably be lost.

The configuration for a non authenticated SSO account would look like this:

# -----------
# SSO Account Configs
# -----------
SSO_SERVER_URL = 'url and port to node' # i.e. '127.0.0.1:10009'
SSO_CERT_PATH = '/path/to/tls/certificate' # i.e. '\lnd\alice\tls.cert'
SSO_MACAROON_PATH = '/path/to/macaroon/folder' # i.e. '\lnd\alice\data\chain\bitcoin\regtest\'
DANGEROUS_NO_SSO_AUTH = 'true' # Default: false

To login to this account go to the following url:

http://localhost:3000/sso?token=1

Server Accounts

You can add accounts on the server by adding this parameter to the .env file:

# -----------
# Account Configs
# -----------
ACCOUNT_CONFIG_PATH = '/path/to/config/file.yaml' # i.e. '/data/thubConfig.yaml'

You must also add a YAML file at that location with the following format:

masterPassword: 'password' # Default password unless defined in account
accounts:
  - name: 'Account 1'
    serverUrl: 'url:port'
    macaroonPath: '/path/to/admin.macaroon'
    certificatePath: '/path/to/tls.cert'
    password: 'password for account 1'
  - name: 'Account 2'
    serverUrl: 'url:port'
    macaroonPath: '/path/to/admin.macaroon'
    certificatePath: '/path/to/tls.cert'
    # password: Leave without password and it will use the master password
  - name: 'Account 3'
    serverUrl: 'url:port'
    macaroon: '0201056...' # HEX or Base64 encoded macaroon
    certificate: '0202045c...' # HEX or Base64 encoded certificate
    password: 'password for account 3'

Notice you can specify either macaroonPath and certificatePath or macaroon and certificate. Note that the port in serverUrl should be the gRPC port that LND is listening on.

Remote access

If you want to access lnd remotely, the setting below should be added to lnd.conf.

# option 1) when accessing by IP
tlsextraip=<externally-reachable-ip-address>
rpclisten=0.0.0.0:10009
 
# option 2) when accessing by domain
tlsextradomain=<externally-reachable-domain-name>
rpclisten=0.0.0.0:10009

Account with environment variables

It's possible to set different parts of the accounts based on environment variables.

You can use the following environment variables: YML_ENV_1, YML_ENV_2, YML_ENV_3, YML_ENV_4 and fill your accounts in the following way:

accounts:
  - name: '{YML_ENV_1}'
    serverUrl: '{YML_ENV_2}'
    macaroon: 'macaroonforthisaccount'
    certificate: '{YML_ENV_4}'

ThunderHub will take care of replacing the fields with the correct environment variables. The {YML_ENV_[1-4]} can only be used for fields inside the accounts. So for example using it for the masterPassword will not work.

Account with LND directory

You can also specify the main LND directory and ThunderHub will look for the certificate and the macaroon in the default folders (based on the network).

Default folders (assuming LND is at path /lnd):

  • Certificate: /lnd/tls.cert
  • Macaroon: /lnd/data/chain/bitcoin/[mainnet | testnet | regtest]/admin.macaroon

The YAML file for this example would be:

masterPassword: 'password' # Default password unless defined in account
defaultNetwork: 'testnet' # Default network unless defined in account
accounts:
  - name: 'Account1'
    serverUrl: 'url:port'
    # network: Leave without network and it will use the default network
    lndDir: '/path/to/lnd'
  - name: 'Account2'
    serverUrl: 'url:port'
    network: 'mainnet'
    lndDir: '/path/to/lnd'

If you don't specify defaultNetwork then mainnet is used as the default.

Please mind that lndDir property will not work in case of Remote access

Encrypted Macaroons

You can use AES encrypted macaroons and have ThunderHub decrypt them and store them in memory. This allows you to have encrypted macaroons on your server and avoid having them in cleartext.

Macaroons should be AES encrypted. This is an example for Javascript:

const encrypted = CryptoJS.AES.encrypt(
  'Hex or Base64 encoded Macaroon',
  'Secret Passphrase'
).toString();

You can use the macaroonPath field and let ThunderHub look for the file or directly use the macaroon field and paste your encrypted macaroon.

You must let ThunderHub know that the macaroon is encrypted by adding an encrypted field to your account like such:

masterPassword: 'password'
accounts:
  - name: 'Account 1'
    serverUrl: 'url:port'
    macaroonPath: '/path/to/encrypted.admin.macaroon'
    encrypted: true # This field is necessary
  - name: 'Account 2'
    serverUrl: 'url:port'
    macaroon: 'EnCrYpTeD-MaCaRoOn'
    encrypted: true # This field is necessary

To login you must use the same secret passphrase that you used to encrypt the macaroon.

Security

On the first start of the server, the masterPassword and all account password fields will be hashed and the file will be overwritten with these new values to avoid having cleartext passwords on the server.

Privacy Configs

Prices and Fees ThunderHub fetches fiat prices from Blockchain.com (opens in a new tab)'s api and bitcoin on chain fees from Earn.com (opens in a new tab)'s api.

If you want to deactivate these requests you can set FETCH_PRICES=false and FETCH_FEES=false in your .env file or manually change them inside the settings view of ThunderHub.

LnMarkets ThunderHub can connect to the LnMarkets API. You can disable this option by setting DISABLE_LNMARKETS=true in your .env file.

Links ThunderHub shows you links for quick viewing of nodes by public key on 1ml.com (opens in a new tab) and for viewing onchain transactions on Blockchain.com (opens in a new tab).

If you don't want to show these links, you can set DISABLE_LINKS=true in your .env file.

Version Check ThunderHub gets the latest available version from Github (opens in a new tab) and shows you a message if you are on an older version.

If you want to disable this option you can set NO_VERSION_CHECK=true in your .env file.

Running on different base path

Adding a BASE_PATH will run the ThunderHub server on a different base path.

# -----------
# Server Configs
# -----------
BASE_PATH = '[Base path where you want to have thunderhub running i.e. '/btcpay']' # Default: ''

For example:

  • by default ThunderHub runs on http://localhost:3000
  • base path of /thub runs ThunderHub on http://localhost:3000/thub

You need to add this environment variable BEFORE building the application

There is a prebuilt Docker (opens in a new tab) image with a preset BASE_PATH=/thub in case you need it and prefer not building your own Docker image.

# Normal docker image
docker pull apotdevin/thunderhub:v0.11.1
 
# Preset basePath docker image
docker pull apotdevin/thunderhub:base-v0.11.1

To build your own docker image with the basePath of your choice you can use docker build --build-arg BASE_PATH='/thub' -t myOwnDockerImage .

You can run ThunderHub behind a proxy with the following configuration (NGINX example):

location /thub {
  proxy_pass http://localhost:3000/thub;
}
👋 Intro🌩️ Installation