How to upgrade Fulcrum v1.x to v2.0 on MiniBolt

A detailed step-by-step guide to upgrading Fulcrum to the new major version 2.0 on MiniBolt.

What's New in Fulcrum 2.0#

Database Reliability - one of the main weaknesses of Fulcrum 1.x was that should the process be killed at an inopportune time, or should abrupt powerloss or kernel-level crash occur at an inopportune time, there was always a risk that the datadir would get corrupted and the admin would be forced to do a full database resynch. This is no longer the case!
Platform Neutrality - database format is now 100% platform-neutral. This means it should be possible to always copy datadirs around regardless if transferring them from Windows, Linux, BSD, macOS, and regardless of platform architecture (including big endian platforms).
Improved database performance.
utxo-cache option has been removed, but it is still possible to use db_mem to help with initial synchronization speed.

Source: https://github.com/cculianu/Fulcrum/releases/tag/v2.0.0

Upgrading from the Fulcrum 1.x Series on a MiniBolt guided-node#

~> Note 1: If you don't know if you'll have enough resources on the machine to handle the migration, it's advisable to free up resources by stopping all possible services running on the machine that aren't critical.

~> Note 2: During the migration, you will need additional and temporary disk space (approximately 84 GB). Make sure you have enough disk space; otherwise, the migration will fail, and you will need to start the synchronization from scratch, deleting the database and recreating it.

With the user admin, stop all non-critical services you can (Fulcrum included) with sudo systemctl stop X

sudo systemctl stop btcrpcexplorer fulcrum

~> In this case, we only stopped the essential services that depend on Fulcrum (currently BTC RPC Explorer) along with Fulcrum itself.

Upgrade binaries#

Download binaries

cd /tmp

Set a temporary version environment variable for the installation

VERSION=2.0.0

Download the application, checksums, and signature

wget https://github.com/cculianu/Fulcrum/releases/download/v$VERSION/Fulcrum-$VERSION-x86_64-linux.tar.gz

wget https://github.com/cculianu/Fulcrum/releases/download/v$VERSION/Fulcrum-$VERSION-shasums.txt.asc

wget https://github.com/cculianu/Fulcrum/releases/download/v$VERSION/Fulcrum-$VERSION-shasums.txt

Signature check

Get the public key from the Fulcrum developer

curl https://raw.githubusercontent.com/Electron-Cash/keys-n-hashes/master/pubkeys/calinkey.txt | gpg --import

Expected output:

[...]
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2328  100  2328    0     0   8449      0 --:--:-- --:--:-- --:--:--  8434
gpg: key 21810A542031C02C: "Calin Culianu (NilacTheGrim) <calin.culianu@gmail.com>" imported
gpg: Total number processed: 1
gpg:              unchanged: 1
[...]

Verify the signature of the text file containing the checksums for the application

gpg --verify Fulcrum-$VERSION-shasums.txt.asc Fulcrum-$VERSION-shasums.txt

Expected output:

[...]
gpg: Good signature from "Calin Culianu (NilacTheGrim) <calin.culianu@gmail.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: D465 135F 97D0 047E 18E9  9DC3 2181 0A54 2031 C02C
[...]

Checksum check

Verify the signed checksum against the actual checksum of your download

grep 'x86_64-linux.tar.gz' Fulcrum-$VERSION-shasums.txt | sha256sum --check

Example of expected output:

Fulcrum-1.9.4-x86_64-linux.tar.gz: OK

Extract it

tar -xzvf Fulcrum-$VERSION-x86_64-linux.tar.gz

Example of expected output:

Fulcrum-1.11.1-amd64-linux/
Fulcrum-1.11.1-amd64-linux/man/
Fulcrum-1.11.1-amd64-linux/man/Fulcrum.1
Fulcrum-1.11.1-amd64-linux/FulcrumAdmin
Fulcrum-1.11.1-amd64-linux/fulcrum-example-config.conf
Fulcrum-1.11.1-amd64-linux/LICENSE.txt
Fulcrum-1.11.1-amd64-linux/Fulcrum
Fulcrum-1.11.1-amd64-linux/unix-man-page.md
Fulcrum-1.11.1-amd64-linux/fulcrum-quick-config.conf

Binaries installation

Install it

sudo install -m 0755 -o root -g root -t /usr/local/bin Fulcrum-$VERSION-x86_64-linux/Fulcrum

Check the correct installation, requesting the version

Fulcrum --version

Example of expected output:

Fulcrum 2.0 (Release df51b8a)
Protocol: version min: 1.4, version max: 1.5.3
compiled: gcc 13.1.0
[...]

(Optional) Delete the installation files of the tmp folder

sudo rm -r Fulcrum-$VERSION-x86_64-linux Fulcrum-$VERSION-x86_64-linux.tar.gz Fulcrum-$VERSION-shasums.txt Fulcrum-$VERSION-shasums.txt.asc

Update the configuration file#

Since the utxo-cache option has been removed, we're replacing it with db_mem to help with initial sync speed.

With the user admin, edit the Fulcrum configuration file

sudo nano /data/fulcrum/fulcrum.conf

Replace utxo-cache option with db_mem and lines related, check this diff. The next should be the final result. Save and exit

Note: If you will go to set db_mem = 2048.0 is not needed to add the next db_mem related lines because it is the default one, you can simply delete the related lines with utxo-cache and go to the next step.

# MiniBolt: fulcrum configuration
# /data/fulcrum/fulcrum.conf

## Bitcoin Core settings
bitcoind = 127.0.0.1:8332
rpccookie = /data/bitcoin/.cookie

## Fulcrum server general settings
datadir = /data/fulcrum/fulcrum_db
cert = /data/fulcrum/cert.pem
key = /data/fulcrum/key.pem
ssl = 0.0.0.0:50002
tcp = 0.0.0.0:50001
peering = false
zmq_allow_hashtx = true

# Max RocksDB Memory in MiB - DEFAULT: 2048.0
# (this applies in initial synchronization and daily operation)
# recommended: db_mem=1/2 x RAM available, e.g, 4GB RAM -> db_mem = 2048.0
db_mem = 2048.0

# Banner
banner = /data/fulcrum/fulcrum-banner.txt

Migrate database#

Since the database format has been completely redone, the database is no longer backward compatible with older Fulcrum versions.

Modify the systemd unit

We are going to upgrade our existing database to the new format using the systemd file and passing the one-time flag --db-upgrade the first time we run Fulcrum 2.0 when upgrading from a 1.x install.

With the user admin, edit the systemd unit

sudo nano /etc/systemd/system/fulcrum.service

Replace the line ExecStart to add the --db-upgrade flag, see the diff. The next should be the final result. Save and exit

# MiniBolt: systemd unit for Fulcrum
# /etc/systemd/system/fulcrum.service

[Unit]
Description=Fulcrum
Requires=bitcoind.service
After=bitcoind.service

StartLimitBurst=2
StartLimitIntervalSec=20

[Service]
ExecStart=/usr/local/bin/Fulcrum --db-upgrade /data/fulcrum/fulcrum.conf

User=fulcrum
Group=fulcrum

# Process management
####################
Type=simple
KillSignal=SIGINT
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target

Reload the systemd daemon to apply changes

sudo systemctl daemon-reload

Prepare "fulcrum" monitoring by the systemd journal and check the logging output. You can exit monitoring at any time with Ctrl-C

journalctl -fu fulcrum

Run the database migration

To keep an eye on the software movements, create a new SSH session to the MiniBolt node, and log in as "admin"

Start Fulcrum to initiate the database migration

sudo systemctl start fulcrum

Example of expected output on the first terminal with journalctl -fu fulcrum ⬇️

~> Note 1: The upgrade process takes seconds to minutes on testnet, and around an hour or more (depending on hardware) on mainnet.

~> Note 2: When you see logs like this SrvMgr: starting 2 services ..., which means that the Fulcrum database is fully migrated:

[...]
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.705] SrvMgr: starting 2 services ...
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.706] Starting listener service for TcpSrv 0.0.0.0:50001 ...
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.706] Service started, listening for connections on 0.0.0.0:50001
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.706] Starting listener service for SslSrv 0.0.0.0:50002 ...
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.706] Service started, listening for connections on 0.0.0.0:50002
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.707] <Controller> Starting ZMQ Notifier (hashtx) ...
Jun 09 10:28:56 minibolt Fulcrum[3345722]: [2024-06-09 10:28:56.707] <Controller> Starting ZMQ Notifier (hashblock) ...
[...]

When Fulcrum has finally migrated the database, stop it, to proceed with the systemd file modification revert

sudo systemctl stop fulcrum

Revert the systemd file's previous change. Edit the systemd file with

sudo nano /etc/systemd/system/fulcrum.service

Delete the --db-upgrade flag on the ExecStart line. See the diff. The next should be the final result. Save and exit

# MiniBolt: systemd unit for Fulcrum
# /etc/systemd/system/fulcrum.service

[Unit]
Description=Fulcrum
Requires=bitcoind.service
After=bitcoind.service

StartLimitBurst=2
StartLimitIntervalSec=20

[Service]
ExecStart=/usr/local/bin/Fulcrum /data/fulcrum/fulcrum.conf

User=fulcrum
Group=fulcrum

# Process management
####################
Type=simple
KillSignal=SIGINT
TimeoutStopSec=300

[Install]
WantedBy=multi-user.target

Reload the systemd daemon to apply changes

sudo systemctl daemon-reload

Start fulcrum again

sudo systemctl start fulcrum

Start dependencies, and any services you may have stopped to perform the Fulcrum migration

sudo systemctl start btcrpcexplorer

~> Monitor the logs with journalctl (journalctl -fu "X") to ensure all is properly running as before.

Enjoy the new shiny and resilient Fulcrum, MiniBolter!💙

How to upgrade Fulcrum v1.x to v2.0 on MiniBolt

What's New in Fulcrum 2.0#

Upgrading from the Fulcrum 1.x Series on a MiniBolt guided-node#

Upgrade binaries#

Download binaries

Signature check

Checksum check

Binaries installation

Update the configuration file#

Migrate database#

Modify the systemd unit

Run the database migration

Written by

Comments

Contents