Bitcoin Node Workshop Build Your Own Bitcoin Node

Explorer

In this section we'll install BTC RPC Explorer, an open source Node.js application for exploring the Bitcoin blockchain through Bitcoin Core's RPC interface. While Mempool provides a modern graphical view of the blockchain, Explorer exposes more of Bitcoin Core's internal data and RPC functionality, making it an excellent educational tool.

Explorer connects to Bitcoin Core for blockchain data and uses electrs for address and transaction queries.

The GitHub repository can be found here:

github.com/janoside/btc-rpc-explorer

A link to the latest release can be found on the right-hand side of the page. Make note of the latest release number. At the time of writing, this workshop uses v3.5.1.

These are the files and directories we'll use:

/etc/btc-rpc-explorer.env                Configuration
/etc/systemd/system/explorer.service     System service
/usr/local/lib/btc-rpc-explorer          Git clone and application files

From the Terminal program on a Mac or Linux computer, or PowerShell on Windows, connect to your Bitcoin node:

ssh nelson@bitcoin-node.local

Become superuser.

su -

Install Debian dependencies

Check whether Node.js, npm and Git are installed:

node --version
npm --version
git --version

Install them if required:

apt install git nodejs npm

Create the Explorer user

Create a dedicated system account to run Explorer:

useradd \
    --system \
    --no-create-home \
    --home-dir /nonexistent \
    --shell /usr/sbin/nologin \
    explorer

Download Explorer

Clone the Explorer repository directly into the installation directory:

git clone https://github.com/janoside/btc-rpc-explorer.git /usr/local/lib/btc-rpc-explorer

Change into the Explorer directory:

cd /usr/local/lib/btc-rpc-explorer

Verify the release

The v3.5.1 tag is not cryptographically signed, so it cannot be verified with git tag -v in the same way as RTL. The commit referenced by the tag is signed, however, and can be verified before it is checked out.

Download and import the maintainer's public keys published by GitHub:

curl https://github.com/janoside.gpg | gpg --import

Display the fingerprint of the key used to sign the release commit:

gpg --fingerprint B326ACF51F317B69

For v3.5.1, the complete fingerprint should be:

F579 929B 39B1 19CC 7B0B  B71F B326 ACF5 1F31 7B69

The fingerprint should also be compared with an independently trusted source identifying it as the maintainer's key. Importing a key from GitHub and verifying a signature with that same key confirms consistency, but does not by itself prove the owner's identity.

Verify the signed commit referenced by the release tag:

git verify-commit 'v3.5.1^{commit}'

You should see a Good signature made with the full fingerprint shown above. Do not continue if Git reports a bad signature or if the fingerprint differs.

Confirm that the tag resolves to the release commit listed on the official GitHub Releases page:

git rev-parse 'v3.5.1^{commit}'

For v3.5.1, this should display:

8ed77ab225f5507c521b570d5240624de597ad44

Check out the verified release:

git checkout v3.5.1

Confirm that the checked-out commit is the one you verified:

git rev-parse HEAD

It should display the same commit hash shown above.

The checkout places the repository in a detached HEAD state. This is expected because the installation is pinned to a specific release rather than following the changing default branch.

Install Explorer

Install the production dependencies recorded in the npm lock file:

npm ci --omit=dev

Using npm ci installs the dependency versions in package-lock.json, providing a repeatable installation.

Configure Explorer

Explorer uses an environment file to store its configuration.

Create the configuration file:

nano /etc/btc-rpc-explorer.env

Add the following configuration:

BTCEXP_HOST=127.0.0.1
BTCEXP_PORT=3002

BTCEXP_BITCOIND_HOST=127.0.0.1
BTCEXP_BITCOIND_PORT=8332
BTCEXP_BITCOIND_USER=explorer
BTCEXP_BITCOIND_PASS=RPC-PASSWORD-HERE
BTCEXP_BITCOIND_RPC_TIMEOUT=10000

BTCEXP_ADDRESS_API=electrum
BTCEXP_ELECTRUM_SERVERS=tcp://127.0.0.1:50001
BTCEXP_ELECTRUM_TXINDEX=true

BTCEXP_PRIVACY_MODE=true
BTCEXP_NO_RATES=true
BTCEXP_SLOW_DEVICE_MODE=true

BTCEXP_UI_TIMEZONE=local
BTCEXP_UI_THEME=dark

We'll create the RPC user and replace the password placeholder in the next step.

Create the RPC user

Explorer communicates with Bitcoin Core using RPC authentication.

Change to the rpcauth directory for the installed Bitcoin Core version:

cd /usr/local/lib/bitcoin/bitcoin-31.0/share/rpcauth

Generate an rpcauth entry for Explorer:

python3 rpcauth.py explorer

The script displays two important values:

  • An rpcauth= line.
  • A randomly generated password.

Copy the rpcauth= line into /etc/bitcoin.conf.

Replace RPC-PASSWORD-HERE in /etc/btc-rpc-explorer.env with the generated password.

Restrict access to the environment file because it contains the RPC password:

chown root:explorer /etc/btc-rpc-explorer.env
chmod 640 /etc/btc-rpc-explorer.env

Restart Bitcoin Core so the new RPC credentials take effect:

systemctl restart bitcoind

Create the system service

Create the service:

nano /etc/systemd/system/explorer.service

Add the following:

[Unit]
Description=BTC RPC Explorer
After=network-online.target bitcoind.service electrs.service
Wants=network-online.target bitcoind.service electrs.service

[Service]
User=explorer
Group=explorer
WorkingDirectory=/usr/local/lib/btc-rpc-explorer
EnvironmentFile=/etc/btc-rpc-explorer.env
ExecStart=/usr/bin/npm start
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Reload the systemd configuration:

systemctl daemon-reload

Enable Explorer so it starts automatically when the computer boots:

systemctl enable explorer

Start Explorer:

systemctl start explorer

Verify that it is running:

systemctl status explorer

View its log if it does not start correctly:

journalctl -u explorer -f

Configure Apache

Explorer listens only on the loopback interface. Apache provides access to the application from the local network.

Open the Apache ports configuration:

nano /etc/apache2/ports.conf

Add the following line if it is not already present:

Listen 4082

Create the virtual host:

nano /etc/apache2/sites-available/explorer.conf

Add the following configuration:

<VirtualHost *:4082>

    ProxyPreserveHost On
    ProxyRequests Off

    ProxyPass        / http://127.0.0.1:3002/
    ProxyPassReverse / http://127.0.0.1:3002/

    ErrorLog ${APACHE_LOG_DIR}/explorer-error.log
    CustomLog ${APACHE_LOG_DIR}/explorer-access.log combined

</VirtualHost>

Enable the Apache proxy modules if they are not already enabled:

a2enmod proxy proxy_http

Enable the site:

a2ensite explorer

Reload Apache:

systemctl reload apache2

Test the installation

Confirm that Explorer is responding locally:

curl -I http://127.0.0.1:3002/

Confirm that the Apache reverse proxy is working:

curl -I http://127.0.0.1:4082/

Finally, open a web browser and browse to:

http://bitcoin-node.local:4082/

The Explorer home page should be displayed.

Dashboard integration

If you are also installing the Dashboard from this workshop, configure the Explorer tab to use the Apache reverse proxy rather than connecting directly to Explorer's internal port. This keeps the application bound to the loopback interface while providing a stable public endpoint through Apache.

Upgrading Explorer

Before upgrading, read the release notes and note the new release tag. Then stop Explorer, fetch the new tags, check out the selected release and reinstall the locked production dependencies:

systemctl stop explorer
cd /usr/local/lib/btc-rpc-explorer
git fetch --tags
git checkout NEW-RELEASE-TAG
npm ci --omit=dev
systemctl start explorer

At this point, BTC RPC Explorer is installed and running.