From Source

Building from source is the right path if you want to contribute, run a customized build (different BASE_PATH, patched dependencies), or just don't want Docker in the loop.

Requirements

• Node.js 24 or newer. The repo pins v24.13.1 in .nvmrc — if you use nvm or fnm, run nvm use / fnm use after cloning.
• npm — bundled with Node.

Install and run

git clone https://github.com/apotdevin/thunderhub.git
cd thunderhub
npm install
npm run build
npm start

ThunderHub serves on http://localhost:3000. Override with PORT=4000 npm start (or set it in .env.local).

For a production server, prune devDependencies after the build to shave the install footprint:

npm prune --production

Development mode

Hot-reloading dev server (NestJS + Vite in watch mode):

npm run start:dev

The repo also exposes a regtest dev environment with two litd nodes — see Developer environment.

Configure

ThunderHub reads .env (committed defaults) then .env.local (your overrides). Create .env.local and put any environment variables there — they survive git pull. The full list lives in the environment variable reference; the most common starting points:

ACCOUNT_CONFIG_PATH='/path/to/thubConfig.yaml'
# OR — to use the database mode instead
DB_TYPE='sqlite'
DB_SQLITE_PATH='/path/to/thunderhub.db'
DB_ENCRYPTION_KEY='<64-char hex from `openssl rand -hex 32`>'

See Accounts to decide which mode to use.

Updating

npm run update

That script wraps git pull && npm install && npm run build && npm start. To do it by hand:

git pull
npm install
npm run build
npm start

Your .env.local and YAML / database files are untouched.

Custom base path

To serve under a URL prefix (e.g. /thub behind a reverse proxy), set BASE_PATH before running npm run build — it's baked into the client bundle. Details in Reverse proxy.