One of the largest Bitcoin payment providers BitPay has been under the fire from Bitcoiners for quite a while.

The community called for a boycott which was smartly used by a developer Nicolas Dorier to his advantage.

Nicolas has created an open-source and self-hosted BitPay-compatible payment gateway called BTCPayServer which has been well received by the community.

While there are many guides on how to set it up using Docker and other methods, I like to have control over what I install on my server while also learning how it works.

If you for whatever reason prefer a manual installation of BTCPayServer, I wrote a step-by-step guide on how to do that.

This tutorial is written for Ubuntu 18.04 but should work on older versions and other Debian-based distributions too.

Before you start, make sure you have Bitcoin Core and Lightning Network node running.

Install Dependencies

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

Install .NET Core SDK

Go to your Downloads folder or any other folder that you use to store temporary files:

cd ~/Downloads

and download Microsoft Packages necessary for the .NET Core SDK:

wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.asc.gpg

sudo mv microsoft.asc.gpg /etc/apt/trusted.gpg.d/

wget -q https://packages.microsoft.com/config/ubuntu/$(lsb_release -sr)/prod.list

sudo mv prod.list /etc/apt/sources.list.d/microsoft-prod.list

Update the package cache and install the .NET Core:

sudo apt-get install apt-transport-https

sudo apt-get update

sudo apt-get install dotnet-sdk-3.1

Install NBXplorer

We'll need to install NBXplorer In order to track incoming on-chain transactions.

Create the source folder if you haven't already and open it:

mkdir ~/source

cd ~/source

Clone the repository and build the code:

git clone https://github.com/dgarage/NBXplorer

cd NBXplorer

./build.sh

Create the data folder:

mkdir -p ~/.nbxplorer/Main

cd ~/.nbxplorer/Main

and a new config file:

touch settings.config

Open the file with the editor of your choice and add the following lines:

btc.rpc.auth=<bitcoind rpc user>:<bitcoind rpc password>

port=24445

mainnet=1

Make sure to use your bitcoind's rpc login credentials. You can find them with the command:

cat ~/.bitcoin/bitcoin.conf | grep rpc

Test if everything is set up correctly:

/usr/bin/dotnet ~/source/NBXplorer/NBXplorer/bin/Release/netcoreapp2.1/NBXplorer.dll -c ~/.nbxplorer/Main/settings.config

If so, hit the ctrl+c to kill the process and download the Systemd service:

cd /usr/lib/systemd/system

sudo wget https://gist.githubusercontent.com/mariodian/de873b969e70eca4d0a7673efd697d0a/raw/acfc70c5694cd53d8a3df7ff54a35ff2caba7532/nbxplorer.service

Edit the file according to your environment.

Enable the service, start it and check the status:

sudo systemctl enable nbxplorer.service

sudo service nbxplorer start

sudo service nbxplorer status

If you see no errors go to the next step.

Install PostgreSQL

I wasn't able to set up BTCPayServer with MySQL/MariaDB so I was forced to use PostgreSQL.

Install it first and open a shell prompt as a newly created system user:

sudo apt install postgresql postgresql-contrib

sudo -i -u postgres

Create a new database user:

createuser --pwprompt --interactive

Type in the following (you can change satoshi , to any username you like):

Create a new database:

createdb -O satoshi btcpayserver

If you see no errors exit the shell:

exit

Install BTCPayServer

Clone the repository and build the code:

cd ~/source

git clone https://github.com/btcpayserver/btcpayserver.git

cd btcpayserver

./build.sh

Create the data folder:

mkdir -p ~/.btcpayserver/Main

cd ~/.btcpayserver/Main

and a new config file:

touch settings.config

Get the LND's certificate fingerprint and paste it into the below config file.

openssl x509 -noout -fingerprint -sha256 -inform pem -in ~/.lnd/tls.cert

Open settings.config and add the following lines:

network=mainnet

port=23001

bind=0.0.0.0

chains=btc

BTC.explorer.url=http://127.0.0.1:24445

BTC.lightning=type=lnd-rest;server=https://127.0.0.1:8080/;macaroonfilepath=~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon;certthumbprint=<finger print>

postgres=User ID=<your db user>;Password=<your db password>;Host=localhost;Port=5432;Database=btcpayserver;

Change the highlighted "variables" according to your settings.

Check if everything is working correctly.

/usr/bin/dotnet run -p ~i/source/btcpayserver/BTCPayServer/BTCPayServer.csproj -c ~/.btcpayserver/Main/settings.config --network=mainnet

If so, hit ctrl+c to kill the process and download the Systemd service:

cd /usr/lib/systemd/system

sudo wget https://gist.githubusercontent.com/mariodian/07bb13da314e2a321784b380f543651a/raw/6cef554d9e8311e683a017d5e63a07822dee7642/btcpayserver.service

Edit the file based on your environment.

Enable the service, start it and check whether it's running correctly:

sudo systemctl enable btcpayserver.service

sudo service btcpayserver start

sudo service btcpayserver status

Congrats, you just got past the hardest part!

Allow incoming connections (optional)

If you want to run your server remotely, you will have to open a port 23001.

First, go to your router settings and find a section along the lines of "Virtual Server" or "Port Forwarding" and set up a port forwarding on the above-mentioned port.

Then go back to your linux machine and open the port with iptables:

sudo iptables -A INPUT -p tcp --dport 23001 -j ACCEPT

If you use iptables-save run the following too:

sudo iptables-save > /etc/iptables/rules.v4

You should be now able to connect to your server from a different machine.

Setup BTCPayServer

Go to your BTCPayServer administration, Register a new admin account and login.

Now, go to Stores and click Create a new store. When done go to the store settings and scroll down to Derivation Scheme.

Under the "BTC" click Modify and on your computer/phone open a wallet that supports BIP32.

For the purpose of the tutorial, I will use Electrum.

It's recommended to create a fresh wallet instead of using an old one so you don't have to bother rescanning balances on your addresses.

When finished, click Wallet -> Information , copy the Master Public Key, paste it back to BTCPayServer administration, check Enabled, and save it.

Next, scroll down to Lightning nodes (Experimental) and click Modify.

Your Connection string should be set up but if not, paste in the following:

type=lnd-rest;server=https://127.0.0.1:8080/;macaroonfilepath=/home/satoshi/.lnd/data/chain/bitcoin/mainnet/admin.macaroon;certthumbprint=<your cert fingerprint>

Remember to add your LND's certificate fingerprint that you've got earlier and change the home directory to your own one.

Click Test connection and if everything's ok check Enabled and click Submit.

In the case, the server runs on a separate machine that you want to access via a domain name, go to Server Settings -> Maintenance , and in the section Change domain name add your name (you will, of course, have to buy it first).

You will also have to add a CNAME or A DNS record with your domain name provider depending on your setup. Sorry, I can't help you on that one, there are too many providers.

Now you should be able to access your BTCPayServer administration with the new domain name like so: http://domain.ltd:23001 .

To create a POS terminal, go to Apps -> Create a new app and fill out the short form. You will then be taken to the app settings where you can change the list of items via a template.

You can also add a simple Pay button to your website that you can configure in Stores -> Settings -> Pay Button as well as create an invoice manually in Stores -> Invoices -> Create a new invoice. that you can then send to a customer.

Of course, the front-end design of the payment gate is fully customizable so you can set your own logo and colors.

Setup SSL certificate from Let's Encrypt (Optional)

First lets install Apache 2 that will be uses as a reversed proxy.

sudo apt-get install apache2

Enable required modules:

sudo a2enmod rewrite

sudo a2enmod proxy

sudo a2enmod proxy_http

sudo a2enmod proxy_ajp

sudo a2enmod deflate

sudo a2enmod headers

sudo a2enmod proxy_balancer

sudo a2enmod proxy_connect

sudo a2enmod proxy_html

Restart the server:

sudo systemctl restart apache2

Install Let's Encrypt certificate for your domain name. But you can use any other certification authority.

Replace the content of /etc/apache2/sites-enabled/000-default.conf with the following:

<VirtualHost *:80>

ServerAdmin webmaster@localhost

ServerName btcpay.freedomnode.com

RewriteEngine on

RewriteCond %{SERVER_NAME} =btcpay.freedomnode.com

RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]

ErrorLog ${APACHE_LOG_DIR}/error.log

CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

Change ServerName based on your needs.

Then, replace the content of /etc/apache2/sites-enabled/000-default-le-ssl.conf with the following:

<IfModule mod_ssl.c>

<VirtualHost *:443>

ServerAdmin webmaster@localhost

ServerName btcpay.freedomnode.com

ErrorLog ${APACHE_LOG_DIR}/error.log

CustomLog ${APACHE_LOG_DIR}/access.log combined

ProxyPass "/" "http://127.0.0.1:23001/"

ProxyPassReverse / "http://127.0.0.1:23001/"

ProxyPreserveHost On

SSLCertificateFile /etc/letsencrypt/live/btcpay.freedomnode.com/fullchain.pem

SSLCertificateKeyFile /etc/letsencrypt/live/btcpay.freedomnode.com/privkey.pem

Include /etc/letsencrypt/options-ssl-apache.conf

</VirtualHost>

</IfModule>

Again, edit ServerName and make sure SSLCertificateFile and SSLCertificateKeyFile point to right files.

Reload the server:

sudo systemctl reload apache2

Now go back to ~/.btcpayserver/Main/settings.config and add:

externalurl=https://btcpay.freedomnode.com

Once again, change the server name to your own one.

You can also remove bind=0.0.0.0 from the configuration because the remote connection will be proxied through Apache from now.

Restart BTCPayServer:

sudo service btcpayserver restart

Open your browser and check if your newly installed SSL certificate works correctly.

*****

I hope you find this tutorial helpful. If you run into any issues let me know in the comments section below.

Feel free to share your online stores running BTCPayServer in the comments too.

P.S. If you appreciate Nicolas' work please support him on his Donation page.

Please let us know what you think in the comments section below.