layout

title

description

tableOfContents

outline

pagination

visible
true

visible

visible
true

visible
true

visible
true

BTCPay Server

BTCPay Server is a free, open-source, and self-hosted Bitcoin payment gateway, which means developers and security auditors can always inspect the code for quality. It enables individuals and businesses to accept Bitcoin payments online or in person without any fees, offering self-sovereignty in the process.

{% hint style="danger" %} Status: Not tested on RaMiX {% endhint %}

{% hint style="danger" %} Difficulty: Hard {% endhint %}

BTCPay Server is a self-hosted and automated invoicing system. At checkout, a customer is presented with an invoice that they pay from their wallet. BTCPay Server follows the status of the invoice through the blockchain and informs you when the payment has been settled so that you can fulfill the order. It also takes care of payment refunding and bitcoin management alongside plenty of other features.

{% hint style="info" %} More information can be found in its documentation, and stay tuned for news on its blog {% endhint %}

Requirements

Bitcoin Core
LND (optional)
NBXplorer
Others
- .NET Core SDK
- PostgreSQL

Preparations

To run the BTCPay Server you will need to install .NET Core SDK, PostgreSQL, and NBXplorer

Firewall

Configure the Firewall to allow incoming HTTP requests

sudo ufw allow 23000/tcp comment 'allow BTCPay Server from anywhere'

Expected output

Rule added

Create the btcpay user & group

We do not want to run BTCPay Server and other related services alongside other services due to security reasons. Therefore, we will create a separate user and run the code under the new user's account.

With user admin, create a new user called btcpay

sudo adduser --disabled-password --gecos "" btcpay

Add btcpay user to the bitcoin and lnd groups

sudo usermod -a -G bitcoin,lnd btcpay

Install .NET Core SDK

With user admin, change to the btcpay user

sudo su - btcpay

We will use the scripted install mode. Download the script

{% code overflow="wrap" %}

wget https://dotnet.microsoft.com/download/dotnet/scripts/v1/dotnet-install.sh

{% endcode %}

Before running this script, you'll need to grant permission for this script to run as an executable

chmod +x ./dotnet-install.sh

Set environment variable version

VERSION=8.0

Install .NET Core SDK

./dotnet-install.sh --channel $VERSION

Example of expected output ⬇️

dotnet-install: Attempting to download using aka.ms link https://dotnetcli.azureedge.net/dotnet/Sdk/6.0.417/dotnet-sdk-6.0.417-linux-x64.tar.gz
dotnet-install: Remote file https://dotnetcli.azureedge.net/dotnet/Sdk/6.0.417/dotnet-sdk-6.0.417-linux-x64.tar.gz size is 186250370 bytes.
dotnet-install: Extracting zip from https://dotnetcli.azureedge.net/dotnet/Sdk/6.0.417/dotnet-sdk-6.0.417-linux-x64.tar.gz
dotnet-install: Downloaded file size is 186250370 bytes.
dotnet-install: The remote and local file sizes are equal.
dotnet-install: Installed version is 6.0.417
dotnet-install: Adding to current process PATH: `/home/btcpay/.dotnet`. Note: This change will be visible only when sourcing script.
dotnet-install: Note that the script does not resolve dependencies during installation.
dotnet-install: To check the list of dependencies, go to https://learn.microsoft.com/dotnet/core/install, select your operating system and check the "Dependencies" section.
dotnet-install: Installation finished successfully.

Add path to dotnet executable

echo 'export DOTNET_ROOT=$HOME/.dotnet' >>~/.bashrc

echo 'export PATH=$PATH:$HOME/.dotnet:$HOME/.dotnet/tools' >>~/.bashrc

(Optional) To improve your privacy, disable the .NET Core SDK telemetry

echo 'export DOTNET_CLI_TELEMETRY_OPTOUT=1' >> ~/.bashrc

source ~/.bashrc

Check .NET SDK is correctly installed

dotnet --version

Example of expected output:

6.0.411

Delete the installation script

rm dotnet-install.sh

Come back to the "admin" user

exit

Install PostgreSQL

With user admin, check if you have already installed PostgreSQL

psql -V

Example of expected output:

psql (PostgreSQL) 16.3 (Ubuntu 16.3-1.pgdg22.04+1)

{% hint style="info" %} If PostgreSQL is not installed (output: Command 'psql' not found), follow this PostgreSQL guide to install it {% endhint %}

Create PostgreSQL databases

With user admin, create a new database for NBXplorer with the postgres user and assign the user admin as the owner

{% code overflow="wrap" %}

sudo -u postgres psql -c "CREATE DATABASE nbxplorer TEMPLATE 'template0' LC_CTYPE 'C' LC_COLLATE 'C' ENCODING 'UTF8' OWNER admin;"

{% endcode %}

Create a new database for BTCPay Server with the postgres user and assign the user admin as the owner

{% code overflow="wrap" %}

sudo -u postgres psql -c "CREATE DATABASE btcpay TEMPLATE 'template0' LC_CTYPE 'C' LC_COLLATE 'C' ENCODING 'UTF8' OWNER admin;"

{% endcode %}

Installation, Configuration & Run

Install NBXplorer

NBXplorer is a minimalist UTXO tracker for HD Wallets, used by BTCPay Server

With user admin, switch to the btcpay user

sudo su - btcpay

Create a src directory and enter the folder

mkdir src && cd src

Set the environment variable version

VERSION=2.5.16

Download the NBXplorer source code and enter the folder

git clone --branch v$VERSION https://github.com/dgarage/NBXplorer.git && cd NBXplorer

Example of expected output ⬇️

Cloning into 'btcpayserver'...
remote: Enumerating objects: 75078, done.
remote: Counting objects: 100% (2765/2765), done.
remote: Compressing objects: 100% (1249/1249), done.
remote: Total 75078 (delta 1834), reused 2203 (delta 1485), pack-reused 72313
Receiving objects: 100% (75078/75078), 51.55 MiB | 4.86 MiB/s, done.
Resolving deltas: 100% (58704/58704), done.
Note: switching to 'a921504bcf619c5e845813b8f994b39147694a97'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

Modify NBXplorer run script

nano +3 run.sh

Comment existing line

#dotnet run --no-launch-profile --no-build -c Release --project "NBXplorer/NBXplorer.csproj" -- $@

Add the next line below. Save and exit

/home/btcpay/.dotnet/dotnet run --no-launch-profile --no-build -c Release --project "NBXplorer/NBXplorer.csproj" -- $@

Modify NBXplorer build script

nano +3 build.sh

Comment next line

#dotnet build -c Release NBXplorer/NBXplorer.csproj

Add the next line below. Save and exit

/home/btcpay/.dotnet/dotnet build -c Release NBXplorer/NBXplorer.csproj

Build NBXplorer

./build.sh

Example of expected output ⬇️

Welcome to .NET 8.0!
---------------------
SDK Version: 8.0.100

----------------
Installed an ASP.NET Core HTTPS development certificate.
To trust the certificate, view the instructions: https://aka.ms/dotnet-https-linux

----------------
Write your first app: https://aka.ms/dotnet-hello-world
Find out what's new: https://aka.ms/dotnet-whats-new
Explore documentation: https://aka.ms/dotnet-docs
Report issues and find source on GitHub: https://github.com/dotnet/core
Use 'dotnet --help' to see available commands or visit: https://aka.ms/dotnet-cli
--------------------------------------------------------------------------------------
MSBuild version 17.8.3+195e7f5a3 for .NET
  Determining projects to restore...
  Restored /home/btcpay/src/NBXplorer/NBXplorer.Client/NBXplorer.Client.csproj (in 30.33 sec).
  Restored /home/btcpay/src/NBXplorer/NBXplorer/NBXplorer.csproj (in 30.35 sec).
  NBXplorer.Client -> /home/btcpay/src/NBXplorer/NBXplorer.Client/bin/Release/netstandard2.1/NBXplorer.Client.dll
  NBXplorer -> /home/btcpay/src/NBXplorer/NBXplorer/bin/Release/net8.0/NBXplorer.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:41.43

{% hint style="info" %} This process can take quite a long time, 10-15 minutes or more, depending on the performance of your device. Please be patient until the prompt shows again {% endhint %}

Check the correct installation

head -n 6 /home/btcpay/src/NBXplorer/NBXplorer/NBXplorer.csproj | grep Version

Example of expected output:

<Version>2.4.3</Version>

NBXplorer configuration

Create the data folder and navigate to it

mkdir -p ~/.nbxplorer/Main

cd ~/.nbxplorer/Main

Create a new config file

nano settings.config

Add the entire next lines. Save and exit

# RaMiX: nbxplorer configuration
# /home/btcpay/.nbxplorer/Main/settings.config

# Bitcoind connection
btc.rpc.cookiefile=/data/bitcoin/.cookie

# Database
postgres=User ID=admin;Password=admin;Host=localhost;Port=5432;Database=nbxplorer;

Go back to the admin user

exit

Create NBXplorer systemd service

As user admin, create the service file

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

Paste the following configuration. Save and exit

# RaMiX: systemd unit for NBXplorer
# /etc/systemd/system/nbxplorer.service

[Unit]
Description=NBXplorer
Requires=bitcoind.service postgresql.service
After=bitcoind.service postgresql.service

[Service]
WorkingDirectory=/home/btcpay/src/NBXplorer
ExecStart=/home/btcpay/src/NBXplorer/run.sh

User=btcpay
Group=btcpay

# Process management
####################
Type=simple
TimeoutSec=120

# Hardening Measures
####################
PrivateTmp=true
ProtectSystem=full
NoNewPrivileges=true
PrivateDevices=true


[Install]
WantedBy=multi-user.target

Enable autoboot (optional)

sudo systemctl enable nbxplorer

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

journalctl -fu nbxplorer

{% hint style="info" %} Keep this terminal open, you'll need to come back here on the next step to monitor the logs {% endhint %}

Running NBXplorer

To keep an eye on the software movements, start your SSH program (eg. PuTTY) a second time, connect to the RaMiX node, and log in as "admin"

With user admin, start the nbxplorer service

sudo systemctl start nbxplorer

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

Jul 05 17:50:20 ramix systemd[1]: Started NBXplorer daemon.
Jul 05 17:50:21 ramix run.sh[2808966]: info: Configuration:  Data Directory: /home/btcpay/.nbxplorer/Main
Jul 05 17:50:21 ramix run.sh[2808966]: info: Configuration:  Configuration File: /home/btcpay/.nbxplorer/Main/settings.config
Jul 05 17:50:21 ramix run.sh[2808966]: info: Configuration:  Network: Mainnet
Jul 05 17:50:21 ramix run.sh[2808966]: info: Configuration:  Supported chains: BTC
Jul 05 17:50:21 ramix run.sh[2808966]: info: Configuration:  DBCache: 50 MB
Jul 05 17:50:21 ramix run.sh[2808966]: info: Configuration:  Network: Mainnet
Jul 05 17:50:21 ramix run.sh[2808966]: info: Configuration:  Supported chains: BTC
Jul 05 17:50:21 ramix run.sh[2808966]: info: Configuration:  DBCache: 50 MB
Jul 05 17:50:21 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Postgres services activated
Jul 05 17:50:21 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 001.Migrations...
Jul 05 17:50:21 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 002.Model...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 003.Legacy...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 004.Fixup...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 005.ToBTCFix...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 006.GetWalletsRecent2...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 007.FasterSaveMatches...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 008.FasterGetUnused...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 009.FasterGetUnused2...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 010.ChangeEventsIdType...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 011.FixGetWalletsRecent...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 012.PerfFixGetWalletsRecent...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 013.FixTrackedTransactions...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 014.FixAddressReuse...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.DatabaseSetup: Execute script 015.AvoidWAL...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.Indexer.BTC: TCP Connection succeed, handshaking...
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.Indexer.BTC: Handshaked
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.Indexer.BTC: Testing RPC connection to http://localhost:8332/
Jul 05 17:50:22 ramix run.sh[2808966]: Hosting environment: Production
Jul 05 17:50:22 ramix run.sh[2808966]: Content root path: /home/btcpay/src/NBXplorer/NBXplorer/bin/Release/net6.0/
Jul 05 17:50:22 ramix run.sh[2808966]: Now listening on: http://127.0.0.1:24444
Jul 05 17:50:22 ramix run.sh[2808966]: Application started. Press Ctrl+C to shut down.
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.Indexer.BTC: RPC connection successful
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.Indexer.BTC: Full node version detected: 250000
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.Indexer.BTC: Has txindex support
Jul 05 17:50:22 ramix run.sh[2808966]: warn: NBXplorer.Indexer.BTC: BTC: Your NBXplorer server is not whitelisted by your node, you should add "whitelist=127.0.0.1" to the configuration file of your node. (Or use whitebind)
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.Events: BTC: Node state changed: NotStarted => NBXplorerSynching
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.Indexer.BTC: Current Index Progress not found, start syncing from the header's chain tip (At height: 797318)
Jul 05 17:50:22 ramix run.sh[2808966]: info: NBXplorer.Events: BTC: Node state changed: NBXplorerSynching => Ready
Jul 05 17:50:23 ramix run.sh[2808966]: info: NBXplorer.Events: BTC: New block 00000000000000000001415583131d3c1da985497830abcf638413226892d4ad (797318)
[..]

Validation

Ensure NBXplorer is running and listening on the default port 24444

sudo ss -tulpn | grep NBXplorer

Expected output:

tcp   LISTEN 0   512    127.0.0.1:24444    0.0.0.0:*    users:(("NBXplorer",pid=2808966,fd=176))

{% hint style="success" %} You have NBXplorer running and prepared for the BTCpay server to use it {% endhint %}

Install BTCPay Server

Switch to the btcpay user

sudo su - btcpay

Go to the src folder

cd src

Set variable environment version

VERSION=2.0.5

Clone the BTCPay Server official GitHub repository and enter the folder

{% code overflow="wrap" %}

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

{% endcode %}

Example of expected output ⬇️

Cloning into 'btcpayserver'...
remote: Enumerating objects: 75078, done.
remote: Counting objects: 100% (2765/2765), done.
remote: Compressing objects: 100% (1249/1249), done.
remote: Total 75078 (delta 1834), reused 2203 (delta 1485), pack-reused 72313
Receiving objects: 100% (75078/75078), 51.55 MiB | 4.86 MiB/s, done.
Resolving deltas: 100% (58704/58704), done.
Note: switching to 'a921504bcf619c5e845813b8f994b39147694a97'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

Turn off this advice by setting config variable advice.detachedHead to false

Modify BTCPay Server run script

nano +4 run.sh

Comment next line

#dotnet "BTCPayServer.dll" $@

Add the next line below. Save and exit

/home/btcpay/.dotnet/dotnet "BTCPayServer.dll" $@

Modify the BTCPay Server build script

nano +3 build.sh

Comment next line

#dotnet publish --no-cache -o BTCPayServer/bin/Release/publish/ -c Release BTCPayServer/BTCPayServer.csproj

Add the next line below. Save and exit

/home/btcpay/.dotnet/dotnet publish --no-cache -o BTCPayServer/bin/Release/publish/ -c Release BTCPayServer/BTCPayServer.csproj

Build BTCPay Server

./build.sh

Example of expected output ⬇️

MSBuild version 17.3.2+561848881 for .NET
  Determining projects to restore...
  Restored /home/btcpay/src/btcpayserver/BTCPayServer.Rating/BTCPayServer.Rating.csproj (in 32.66 sec).
  Restored /home/btcpay/src/btcpayserver/BTCPayServer.Data/BTCPayServer.Data.csproj (in 1.41 sec).
  Restored /home/btcpay/src/btcpayserver/BTCPayServer.Common/BTCPayServer.Common.csproj (in 392 ms).
  Restored /home/btcpay/src/btcpayserver/BTCPayServer.Client/BTCPayServer.Client.csproj (in 1.1 sec).
  Restored /home/btcpay/src/btcpayserver/BTCPayServer.Abstractions/BTCPayServer.Abstractions.csproj (in 8 ms).
  Restored /home/btcpay/src/btcpayserver/BTCPayServer/BTCPayServer.csproj (in 36.6 sec).
  BTCPayServer.Common -> /home/btcpay/src/btcpayserver/BTCPayServer.Common/bin/Release/net6.0/BTCPayServer.Common.dll
  BTCPayServer.Client -> /home/btcpay/src/btcpayserver/BTCPayServer.Client/bin/Release/netstandard2.1/BTCPayServer.Client.dll
  BTCPayServer.Rating -> /home/btcpay/src/btcpayserver/BTCPayServer.Rating/bin/Release/net6.0/BTCPayServer.Rating.dll
  BTCPayServer.Abstractions -> /home/btcpay/src/btcpayserver/BTCPayServer.Abstractions/bin/Release/net6.0/BTCPayServer.Abstractions.dll
  BTCPayServer.Data -> /home/btcpay/src/btcpayserver/BTCPayServer.Data/bin/Release/net6.0/BTCPayServer.Data.dll
/home/btcpay/src/btcpayserver/BTCPayServer/Services/Cheater.cs(37,35): warning CS1998: This async method lacks 'await' operators and will run synchronously. Consider using the 'await' operator to await non-blocking API calls, or 'await Task.Run(...)' to do CPU-bound work on a background thread. [/home/btcpay/src/btcpayserver/BTCPayServer/BTCPayServer.csproj]
  BTCPayServer -> /home/btcpay/src/btcpayserver/BTCPayServer/bin/Release/net6.0/BTCPayServer.dll
  BTCPayServer -> /home/btcpay/src/btcpayserver/BTCPayServer/bin/Release/publish/

{% hint style="info" %} This process can take quite a long time, 10-15 minutes or more, depending on the performance of your device. Please be patient until the prompt shows again {% endhint %}

Check the correct installation

head -n 3 /home/btcpay/src/btcpayserver/Build/Version.csproj | grep Version

Example of expected output:

<Version>1.12.0</Version>

BTCPay Server configuration

Create the data folder and enter it

mkdir -p ~/.btcpayserver/Main && cd ~/.btcpayserver/Main

Create a new config file

nano settings.config

Add the complete following lines

# RaMiX: btcpayserver configuration
# /home/btcpay/.btcpayserver/Main/settings.config

# Server settings
bind=0.0.0.0
socksendpoint=127.0.0.1:9050

# Database
## NBXplorer
explorer.postgres=User ID=admin;Password=admin;Host=localhost;Port=5432;Database=nbxplorer;
## BTCpay server
postgres=User ID=admin;Password=admin;Host=localhost;Port=5432;Database=btcpay;

{% hint style="info" %} -> If you want to connect your Lightning LND node to BTCPay Server too, go to the Connect to your LND internal node optional section

-> The socksendpoint=127.0.0.1:9050 parameter is optional but recommended to increase your privacy, if you want to delete, comment with # before it or delete it directly {% endhint %}

Go back to the admin user

exit

Create BTCPay Server systemd service

As user admin, create the service file

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

Paste the following configuration. Save and exit

# RaMiX: systemd unit for BTCPay Server
# /etc/systemd/system/btcpay.service

[Unit]
Description=BTCPay Server
Requires=nbxplorer.service postgresql.service lnd.service
After=nbxplorer.service postgresql.service lnd.service

[Service]
WorkingDirectory=/home/btcpay/src/btcpayserver
ExecStart=/home/btcpay/src/btcpayserver/run.sh

User=btcpay
Group=btcpay

# Process management
####################
Type=simple
TimeoutSec=120

[Install]
WantedBy=multi-user.target

Enable autoboot (optional)

sudo systemctl enable btcpay

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

journalctl -fu btcpay

{% hint style="info" %} Keep this terminal open, you'll need to come back here on the next step to monitor the logs {% endhint %}

Running BTCPay Server

To keep an eye on the software movements, start your SSH program (eg. PuTTY) a second time, connect to the RaMiX node, and log in as admin

sudo systemctl start btcpay

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

Jul 05 18:01:08 ramix run.sh[2810276]: info: Configuration:  Data Directory: /home/btcpay/.btcpayserver/Main
Jul 05 18:01:08 ramix run.sh[2810276]: info: Configuration:  Configuration File: /home/btcpay/.btcpayserver/Main/settings.config
Jul 05 18:01:09 ramix run.sh[2810276]: info: BTCPayServer.Plugins.PluginManager: Loading plugins from /home/btcpay/.btcpayserver/Plugins
Jul 05 18:01:09 ramix run.sh[2810276]: info: BTCPayServer.Plugins.PluginManager: Adding and executing plugin BTCPayServer - 1.10.3
Jul 05 18:01:09 ramix run.sh[2810276]: info: BTCPayServer.Plugins.PluginManager: Adding and executing plugin BTCPayServer.Plugins.Shopify - 1.10.3
Jul 05 18:01:09 ramix run.sh[2810276]: info: BTCPayServer.Plugins.PluginManager: Adding and executing plugin BTCPayServer.Plugins.PointOfSale - 1.10.3
Jul 05 18:01:09 ramix run.sh[2810276]: info: BTCPayServer.Plugins.PluginManager: Adding and executing plugin BTCPayServer.Plugins.PayButton - 1.10.3
Jul 05 18:01:09 ramix run.sh[2810276]: info: BTCPayServer.Plugins.PluginManager: Adding and executing plugin BTCPayServer.Plugins.NFC - 1.10.3
Jul 05 18:01:09 ramix run.sh[2810276]: info: BTCPayServer.Plugins.PluginManager: Adding and executing plugin BTCPayServer.Plugins.Crowdfund - 1.10.3
Jul 05 18:01:09 ramix run.sh[2810276]: info: Configuration:  Supported chains: BTC
Jul 05 18:01:09 ramix run.sh[2810276]: info: Configuration:  BTC: Explorer url is http://127.0.0.1:24444/
Jul 05 18:01:09 ramix run.sh[2810276]: info: Configuration:  BTC: Cookie file is /home/btcpay/.nbxplorer/Main/.cookie
Jul 05 18:01:09 ramix run.sh[2810276]: info: Configuration:  Network: Mainnet
Jul 05 18:01:13 ramix run.sh[2810276]: info: Configuration:  Root Path: /
Jul 05 18:01:14 ramix run.sh[2810276]: info: PayServer:      Checking if any payment arrived on lightning while the server was offline...
Jul 05 18:01:14 ramix run.sh[2810276]: info: PayServer:      Processing lightning payments...
Jul 05 18:01:14 ramix run.sh[2810276]: info: PayServer:      Starting listening NBXplorer (BTC)
Jul 05 18:01:14 ramix run.sh[2810276]: info: PayServer:      Start watching invoices
Jul 05 18:01:14 ramix run.sh[2810276]: info: PayServer:      Starting payment request expiration watcher
Jul 05 18:01:14 ramix run.sh[2810276]: info: PayServer:      0 pending payment requests being checked since last run
Jul 05 18:01:14 ramix run.sh[2810276]: info: Configuration:  Now listening on: http://127.0.0.1:23000
Jul 05 18:01:14 ramix run.sh[2810276]: info: PayServer:      BTC: Checking if any pending invoice got paid while offline...
Jul 05 18:01:14 ramix run.sh[2810276]: info: PayServer:      BTC: 0 payments happened while offline
Jul 05 18:01:14 ramix run.sh[2810276]: info: PayServer:      Connected to WebSocket of NBXplorer (BTC)
[...]

Validation

Ensure the BTCPay Server is running and listening on the default port 23000

sudo ss -tulpn | grep 23000

Expected output:

tcp   LISTEN 0   512        0.0.0.0:23000   0.0.0.0:*    users:(("dotnet",pid=2811744,fd=320))

Now point your browser, "http://ramix.local:23000" (or your node IP address) like "http://192.168.0.20:23000"

{% hint style="info" %} You can now create the first account to access the dashboard using a real (recommended) or a dummy email + password {% endhint %}

{% hint style="success" %} Congratulations! You now have the amazing BTCPay Server payment processor running {% endhint %}

Extras (optional)

Remote access over Tor

You can easily do so by adding a Tor hidden service on the RaMiX and accessing the BTCPay Server with the Tor browser from any device.

With the user admin, edit the torrc file

sudo nano +63 /etc/tor/torrc --linenumbers

Add the following lines to the location hidden services section, below ## This section is just for location-hidden services ## in the torrc file. Save and exit

# Hidden Service BTCPay Server
HiddenServiceDir /var/lib/tor/hidden_service_btcpay/
HiddenServiceVersion 3
HiddenServicePoWDefensesEnabled 1
HiddenServicePort 80 127.0.0.1:23000

Reload the Tor configuration

sudo systemctl reload tor

Get your connection address

sudo cat /var/lib/tor/hidden_service_btcpay/hostname

Example of expected output:

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

With the Tor browser, you can access this onion address from any device

Connect to your LND internal node

Configure LND

Stay logged as admin user, and configure LND to allow LND REST from anywhere editing the lnd.conf file

sudo nano /data/lnd/lnd.conf

Add the next line under the [Application Options] section. Save and exit

# Specify all ipv4 interfaces to listen on for REST connections
restlisten=0.0.0.0:8080

Restart LND to apply changes

sudo systemctl restart lnd

Ensure the REST port is now binding to the 0.0.0.0 host instead of 127.0.0.1

sudo ss -tulpn | grep lnd | grep 8080

Expected output:

tcp   LISTEN 0      4096         0.0.0.0:8080       0.0.0.0:*    users:(("lnd",pid=774047,fd=32))

Stop BTCPay Server before making changes

sudo systemctl stop btcpay

Modify BTCPay Server configuration

Change to the btcpay user

sudo su - btcpay

Edit the settings.config file

nano .btcpayserver/Main/settings.config

Add the next content to the end of the file. Save and exit

# Lightning internal node connection
BTC.lightning=type=lnd-rest;server=https://127.0.0.1:8080/;macaroonfilepath=/data/lnd/data/chain/bitcoin/mainnet/admin.macaroon;allowinsecure=true

Go back to the admin user

exit

Modify the BTCPay Server systemd service

Modify the next lines of the systemd service file by following this section, adding the lnd.service dependency

Requires=nbxplorer.service lnd.service
After=nbxplorer.service lnd.service

Reload the systemd daemon

sudo systemctl daemon-reload

Start the BTCPay Server again

sudo systemctl start btcpay

{% hint style="info" %} Monitor logs with journalctl -fu btcpay to ensure that all is running well {% endhint %}

Upgrade

Updating to a new release of BTCPay Server or NBXplorer should be straightforward.

Upgrade .NET Core SDK

With user admin, stop BTCPay Server & NBXplorer

sudo systemctl stop btcpay && sudo systemctl stop nbxplorer

Change to the btcpay user

sudo su - btcpay

We will use the scripted install mode. Download the script

wget https://dotnet.microsoft.com/download/dotnet/scripts/v1/dotnet-install.sh

Before running this script, you'll need to grant permission for this script to run as an executable

chmod +x ./dotnet-install.sh

Set the new VERSION environment variable, for example, 6.0 -> 8.0

VERSION=8.0

Install .NET Core SDK

./dotnet-install.sh --channel $VERSION

Example of expected output ⬇️

dotnet-install: Attempting to download using aka.ms link https://dotnetcli.azureedge.net/dotnet/Sdk/6.0.417/dotnet-sdk-6.0.417-linux-x64.tar.gz
dotnet-install: Remote file https://dotnetcli.azureedge.net/dotnet/Sdk/6.0.417/dotnet-sdk-6.0.417-linux-x64.tar.gz size is 186250370 bytes.
dotnet-install: Extracting zip from https://dotnetcli.azureedge.net/dotnet/Sdk/6.0.417/dotnet-sdk-6.0.417-linux-x64.tar.gz
dotnet-install: Downloaded file size is 186250370 bytes.
dotnet-install: The remote and local file sizes are equal.
dotnet-install: Installed version is 6.0.417
dotnet-install: Adding to current process PATH: `/home/btcpay/.dotnet`. Note: This change will be visible only when sourcing script.
dotnet-install: Note that the script does not resolve dependencies during installation.
dotnet-install: To check the list of dependencies, go to https://learn.microsoft.com/dotnet/core/install, select your operating system and check the "Dependencies" section.
dotnet-install: Installation finished successfully.

(Optional) If you haven't done this before, to improve your privacy, disable the .NET Core SDK telemetry

echo 'export DOTNET_CLI_TELEMETRY_OPTOUT=1' >> ~/.bashrc

Apply changes

source ~/.bashrc

Check the new .NET SDK version has been correctly installed

dotnet --version

Example of expected output:

6.0.411

Delete the installation script

rm dotnet-install.sh

Exit to return to the admin user

exit

Upgrade NBXplorer

With user admin, stop BTCPay Server & NBXplorer

sudo systemctl stop btcpay && sudo systemctl stop nbxplorer

Change to the btcpay user

sudo su - btcpay

Enter the src/nbxplorer folder

cd src/NBXplorer

Set the environment variable version

VERSION=2.5.16

Fetch the changes of the latest wish tag

git pull https://github.com/dgarage/NBXplorer.git v$VERSION

Example of expected output:

From https://github.com/dgarage/NBXplorer
 * tag               v2.4.3     -> FETCH_HEAD
Updating c7b5a73..95f28ac
Fast-forward
 Dockerfile.linuxamd64                                              |   4 +-
 Dockerfile.linuxarm32v7                                            |   4 +-
 Dockerfile.linuxarm64v8                                            |   4 +-
 NBXplorer.Client/AssetMoney.cs                                     |   1 -
[...]

{% hint style="info" %} If the prompt shows you "fatal: unable to auto-detect email address (got 'btcpay@ramix.(none)')"⬇️

git config user.email "ramix@dummyemail.com"

git config user.name "RaMiX"

-> And try again the last command {% endhint %}

{% hint style="info" %} If the prompt shows you this:

hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint:   git config pull.rebase false  # merge (the default strategy)
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.

You need to do and exec the before git pull command again:

git config pull.rebase false

{% endhint %}

Press Ctrl+X when the nano automatically opens the MERGE_MSG to no apply modifications
Build it

./build.sh

Example of expected output ⬇️

MSBuild version 17.8.3+195e7f5a3 for .NET
  Determining projects to restore...
  Restored /home/btcpay/src/NBXplorer/NBXplorer.Client/NBXplorer.Client.csproj (in 2.43 sec).
  Restored /home/btcpay/src/NBXplorer/NBXplorer/NBXplorer.csproj (in 2.47 sec).
  NBXplorer.Client -> /home/btcpay/src/NBXplorer/NBXplorer.Client/bin/Release/netstandard2.1/NBXplorer.Client.dll
  NBXplorer -> /home/btcpay/src/NBXplorer/NBXplorer/bin/Release/net8.0/NBXplorer.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:19.80

Check the correct installation update

head -n 6 /home/btcpay/src/NBXplorer/NBXplorer/NBXplorer.csproj | grep Version

Example of expected output:

<Version>2.4.3</Version>

Go back to the admin user

exit

Start the NBXplorer & BTCPay Server again. Monitor logs with journalctl -fu nbxplorer & journalctl -fu btcpay to ensure that all is running well

sudo systemctl start nbxplorer && sudo systemctl start btcpay

Upgrade BTCPay Server

With user admin, stop BTCPay Server

sudo systemctl stop btcpay

Change to the btcpay user

sudo su - btcpay

Enter the src/btcpayserver folder

cd src/btcpayserver

Set the environment variable version

VERSION=2.0.5

Fetch the changes of the latest tag. Press Ctrl+X when the nano automatically opens the MERGE_MSG to apply modifications

{% code overflow="wrap" %}

git pull https://github.com/btcpayserver/btcpayserver.git v$VERSION

{% endcode %}

Example of expected output:

From https://github.com/btcpayserver/btcpayserver
 * tag                   v1.12.0    -> FETCH_HEAD
Updating 541cef55b..6ecfe073e
Fast-forward
 BTCPayServer.Data/ApplicationDbContext.cs                         |  2 +-
 BTCPayServer.Data/Data/AppData.cs                                 | 10 +++++++++-
[...]

{% hint style="info" %} If the prompt shows you "fatal: unable to auto-detect email address (got 'btcpay@ramix.(none)')"⬇️

git config user.email "ramix@dummyemail.com"

git config user.name "RaMiX"

-> And try again the last command {% endhint %}

{% hint style="info" %} If the prompt shows you: fatal: Need to specify how to reconcile divergent branches.⬇️

git config pull.rebase false

-> And try again the last command {% endhint %}

{% hint style="info" %} If the prompts show you logs like these:

Auto-merging BTCPayServer.Abstractions/BTCPayServer.Abstractions.csproj
CONFLICT (content): Merge conflict in BTCPayServer.Abstractions/BTCPayServer.Abstractions.csproj

With the user admin (type exit), you need to delete the BTCPay Server source code:

sudo rm -r /home/btcpay/src/btcpayserver

Follow the Install BTCPay Server section again
Return to the user admin and start BTCPay Server

sudo systemctl start btcpayserver

The prompt shows you logs like these:

[...]
Oct 30 16:26:42 ramix run.sh[3307655]: info: BTCPayServer.Hosting.MigrationStartupTask: Running the migration scripts...
Oct 30 16:26:44 ramix run.sh[3307655]: info: Microsoft.EntityFrameworkCore.Migrations: Applying migration '20231219031609_translationsmigration'.
Oct 30 16:26:44 ramix run.sh[3307655]: info: Microsoft.EntityFrameworkCore.Migrations: Applying migration '20240304003640_addinvoicecolumns'.
Oct 30 16:26:44 ramix run.sh[3307655]: info: Microsoft.EntityFrameworkCore.Migrations: Applying migration '20240317024757_payments_refactor'.
Oct 30 16:26:44 ramix run.sh[3307655]: info: Microsoft.EntityFrameworkCore.Migrations: Applying migration '20240325095923_RemoveCustodian'.
[...]
Oct 30 16:26:48 ramix run.sh[3307655]: info: BTCPayServer.HostedServices.InvoiceBlobMigratorHostedService: Migrating from the beginning
Oct 30 16:26:48 ramix  run.sh[3307655]: info: BTCPayServer.HostedServices.PaymentRequestsMigratorHostedService: Migrating from the beginning
[...]

{% endhint %}

Build it

./build.sh

Example of expected output ⬇️

  Determining projects to restore...
  Restored /home/btcpay/src/btcpayserver/BTCPayServer.Abstractions/BTCPayServer.Abstractions.csproj (in 965 ms).
  Restored /home/btcpay/src/btcpayserver/BTCPayServer.Client/BTCPayServer.Client.csproj (in 965 ms).
  Restored /home/btcpay/src/btcpayserver/BTCPayServer.Common/BTCPayServer.Common.csproj (in 978 ms).
  Restored /home/btcpay/src/btcpayserver/BTCPayServer.Data/BTCPayServer.Data.csproj (in 113 ms).
  Restored /home/btcpay/src/btcpayserver/BTCPayServer.Rating/BTCPayServer.Rating.csproj (in 178 ms).
  Restored /home/btcpay/src/btcpayserver/BTCPayServer/BTCPayServer.csproj (in 1.9 sec).
  BTCPayServer.Client -> /home/btcpay/src/btcpayserver/BTCPayServer.Client/bin/Release/netstandard2.1/BTCPayServer.Client.dll
  BTCPayServer.Common -> /home/btcpay/src/btcpayserver/BTCPayServer.Common/bin/Release/net8.0/BTCPayServer.Common.dll
  BTCPayServer.Rating -> /home/btcpay/src/btcpayserver/BTCPayServer.Rating/bin/Release/net8.0/BTCPayServer.Rating.dll
  BTCPayServer.Abstractions -> /home/btcpay/src/btcpayserver/BTCPayServer.Abstractions/bin/Release/net8.0/BTCPayServer.Abstractions.dll
  BTCPayServer.Data -> /home/btcpay/src/btcpayserver/BTCPayServer.Data/bin/Release/net8.0/BTCPayServer.Data.dll
  BTCPayServer -> /home/btcpay/src/btcpayserver/BTCPayServer/bin/Release/net8.0/BTCPayServer.dll
  BTCPayServer -> /home/btcpay/src/btcpayserver/BTCPayServer/bin/Release/publish/

Check the correct installation update

head -n 3 /home/btcpay/src/btcpayserver/Build/Version.csproj | grep Version

Example of expected output:

<Version>1.12.0</Version>

Go back to the admin user

exit

Start the BTCpay server again. Monitor logs with journalctl -fu btcpay to ensure that all is running well

sudo systemctl start btcpay

Uninstall

Uninstall service

With user admin, stop btcpay and nbxplorer

sudo systemctl stop btcpay && sudo systemctl stop nbxplorer

Disable autoboot (if enabled)

sudo systemctl disable btcpay && sudo systemctl disable nbxplorer

Delete btcpay and nbxplorer services

sudo rm /etc/systemd/system/btcpay.service

sudo rm /etc/systemd/system/nbxplorer.service

Delete user & group

Delete the btcpay user. Don't worry about userdel: btcpay mail spool (/var/mail/btcpay) not found output, the uninstall has been successful

sudo userdel -rf btcpay

Uninstall Firewall configuration & reverse proxy

With the user admin, display the UFW firewall rules, and note the numbers of the rules for BTCPay Server (e.g. X and Y below)

sudo ufw status numbered

Expected output:

[Y] 23000       ALLOW IN    Anywhere          # allow BTCPay Server from anywhere

Delete the rule with the correct number and confirm with yes

sudo ufw delete X

Uninstall Tor hidden service

With the user admin, edit the torrc file

sudo nano +63 /etc/tor/torrc --linenumbers

Comment or remove the btcpay hidden service in the torrc. Save and exit

# Hidden Service BTCPay Server
#HiddenServiceDir /var/lib/tor/hidden_service_btcpay/
#HiddenServiceVersion 3
#HiddenServicePoWDefensesEnabled 1
#HiddenServicePort 80 127.0.0.1:23000

Reload the torrc config

sudo systemctl reload tor

Delete the PostgreSQL databases

With user admin delete the nbxplorer and btcpay databases

{% code overflow="wrap" %}

sudo -u postgres psql -c "DROP DATABASE nbxplorer;" && sudo -u postgres psql -c "DROP DATABASE btcpay;"

{% endcode %}

Port reference

Port	Protocol	Use
24444	TCP	NBXplorer default port
23000	TCP	BTCPay Server default port

Files

btcpay-server.md

Latest commit

History

btcpay-server.md

File metadata and controls

BTCPay Server

Requirements

Preparations

Firewall

Create the btcpay user & group

Install .NET Core SDK

Install PostgreSQL

Create PostgreSQL databases

Installation, Configuration & Run

Install NBXplorer

NBXplorer configuration

Create NBXplorer systemd service

Running NBXplorer

Validation

Install BTCPay Server

BTCPay Server configuration

Create BTCPay Server systemd service

Running BTCPay Server

Validation

Extras (optional)

Remote access over Tor

Connect to your LND internal node

Configure LND

Modify BTCPay Server configuration

Modify the BTCPay Server systemd service

Upgrade

Upgrade .NET Core SDK

Upgrade NBXplorer

Upgrade BTCPay Server

Uninstall

Uninstall service

Delete user & group

Uninstall Firewall configuration & reverse proxy

Uninstall Tor hidden service

Delete the PostgreSQL databases

Port reference