Set up a BTCPay Server on Ubuntu 22.04/20.04 using Docker

​If you are going to use your server to sell services to people in one way or another, you’ll probably need to arrange a possibility to perform the payment with a special payment processor. If you’re interested particularly in Bitcoin (and altcoin) payments, you’ll need a cryptocurrency payment processor, whereby BTCpay may be the solution you’re looking for. If this particular solution has caught you, you’ll be able to install it by following the guide that follows.

Introduction to BTCPay Server

What’s good about BTCpay is that using it won’t require you to use a third-party payment processor. Its peer-to-peer nature provides you with better flexibility and independence and also excludes the possibility of censorship. Besides that, the solution offers a range of further benefits:

• Decentralization and self-sovereignty: Since BTCpay is self-hosted, you and only your are entirely in charge of your payment procedures. This autonomy brings a range of valuable benefits. For instance, there is no censorship and your account cannot be suspended.
• No additional fees: Since you provide the operation of this payment processor you host on your own, there is no one that would require you to pay fees.
• Privacy: BTCPay doesn’t require personally identifiable information from the users. 
• Security: Because of the open-source nature of the solution. it’s in the first place community-driven and receives regular security audits. For this reason, it has a pretty high resistance to attacks. In addition, you bear the unanimous responsibility for your private keys which is another contribution to the general level of security.
• Customization: BTCPay is highly customizable, you can feel free to adjust it according to your vision of your business, providing your customers with a unique payment experience.
• Community and ecosystem: BTCPay has an extensive user community, which provides you with access to reliable support, rich documentation, and plugins for any use case, which again gives you freedom of action to adjust the payment processing according to your personal vision.
• Reduced regulatory compliance: Since no centralized institutions are in any way engaged in BTCPay, you will definitely have much fewer difficulties in terms of regulatory compliance. This is especially the case if your country imposes strict financial regulations.
• Easy integration: The platform is easy to integrate with a range of common e-commerce platforms – WooCommerce, Shopify, Magento, and some others.
• Multi-signature wallet support: BTCPay supports multi-signature wallet, which provides enhanced security of cryptocurrency holdings.
• Lightning Network integration: BTCPay among other things provides Lightning Network support. Lightning Network is a second-layer scaling solution for Bitcoin which will make your transactions quicker and at the same time more cost-efficient.

Server Requirements

BTCPay requires your server to provide the following capacities:

• CPU cores: 2.
• RAM: 4 GB.
• Storage: 600 GB.

Step 1: Installing Docker on Ubuntu 22.04 Server

Using BTCPay Docker will greatly simplify the installation of BTCPay, therefore we are choosing this approach.

Ubuntu should already have docker installed in its software repository. Nevertheless, to make sure that the version you have is the latest, you can install it from Docker’s APT repository.

• SSH your server
• Run the command to add the Docker repository to your server:

echo "deb [signed-by=/etc/apt/keyrings/docker.gpg.key arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list

• Import the Docker GPG key to the Ubuntu system. This way APT will be able to verify the package integrity:

wget --quiet -O - https://download.docker.com/linux/ubuntu/gpg | sudo tee /etc/apt/keyrings/docker.gpg.key

• Install apt-transport-https and ca-certificates package:

sudo apt install apt-transport-https ca-certificates

• Update the package index and install Docker Community Edition

sudo apt update
sudo apt install docker-ce

This should complete the installation of Docker. You can verify it by checking the status:

systemctl status docker

If Docker hasn’t started, you can start it this way:

sudo systemctl restart docker.socket
sudo systemctl restart docker.service

To make it start automatically every time the system boots:

sudo systemctl enable docker

To check the version:

docker -v

Step 2: Setting Up the BTCPay Docker Container

• Switch to root:

sudo su –

• Copy the BTCPay Server repo from GitHub:

sudo apt install git
cd ~
git clone https://github.com/btcpayserver/btcpayserver-docker.git

You’ll be able to find it under ~/btcpayserver-docker. Go there:

cd ~/btcpayserver-docker/

• Run each of these commands separately. This way you’ll set some necessary environmental variables

export BTCPAY_HOST="btcpay.example.com"
export NBITCOIN_NETWORK="mainnet"
export BTCPAYGEN_CRYPTO1="btc"
export BTCPAYGEN_REVERSEPROXY="empty"
export BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;nginx-https"
export BTCPAYGEN_LIGHTNING="lnd"
export BTCPAY_ENABLE_SSH=true

Notes:

BTCPAY_HOST: btcpay.example.com is to be replaced with your hostname.

NBTICOIN_NETWORK: there is a choice between mainnet, testnet or regnet.

BTCPAYGEN_CRYPTO01 is responsible for choosing the supported coin. Here we add bitcoin, you can eventually add further coins.

BTCPAYGEN_REVERSEPROXY: Selecting either nginx, traefix or emtpy.

BTCPAYGEN_EXECLUDE_FRAGMENTS: Disables the generation of TLS certificates. A free Let’s Encrypt TLS can be installed eventually.

BTCPAYGEN_LIGHTING: Choose lnd or clightning to enable lightning networking support.

BTCPAY_ENABLE_SSH: Enable SSH authorized keys management for BTCPAY.

Environmental variables can be checked with:

echo $BTCPAY_HOST

Installing BTCPay Docker container:

. ./btcpay-setup.sh -i

Checking the service status of systemd:

sudo systemctl status btcpayserver.service

Checking the containers of Docker:

sudo docker ps

By default, btcpayserver/btcpayserver Docker container is not to expose the port to the host OS. To fix it, open the docker-compose file in the preferred editor (here nano):

nano ~/btcpayserver-docker/Generated/docker-compose.generated.yml

In the btcpayserver section, add under “ports:”:

    - "49392:49392"

Save and exit. Restart btcpayserver.service:

sudo systemctl restart btcpayserver

Now, you may check the status of Docker container once more:

sudo docker ps

Now the port of the host OS (49392) should be mapped to the port 49392 of Docker.

Step 3: Configuring Nginx Reverse Proxy

• Install the Nginx web server from the default software repo of Ubuntu:

sudo apt install nginx

• Create a virtual host file for the BTCPay server.

sudo nano /etc/nginx/conf.d/btcpay-server.conf

• Configure Nginx as a Reverse Proxy. Inside the btcpay configuration file, add the following configuration. Replace btcpay.example.com with your domain name or server IP:

server {
    listen 80;
    server_name btcpay.example.com;


    location / {
        proxy_pass http://127.0.0.1:23000; # The default BTCPay port is 23000
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

If your BTCPay is running on a different server and uses a different port, you should adjust proxy_pass accordingly.

• Create a Symbolic Link to your Nginx configuration file in the /etc/nginx/sites-enabled/ directory to enable the site:

sudo ln -s /etc/nginx/sites-available/btcpay /etc/nginx/sites-enabled/

• Test your Nginx configuration for syntax errors before applying the changes:

sudo nginx -t

• If no errors popped out during the text, reload Nginx to apply changes:

sudo systemctl reload nginx

• Firewall: Make sure that the firewall of the server allows incoming traffic on port 80. To allow HTTP traffic, you might need to configure the settings of your firewall, like UFW and others.
• Access BTCPay: Make sure that BTCPay is now accessible with your domain name or server IP, that it works properly and without errors.

Step 4: Enabling HTTPS for BTCPay Server

Enabling HTTPS (SSL/TLS) will allow you to benefit from enhanced privacy and security when it comes to data transfer for both you and your customers. The first step here is to obtain an SSL certificate, which you can get from Let’s Encrypt, a trusted authority providing free security certificates. Afterwards, you’ll have to follow the guidelines below to actually enable HTTPS.

• Install Certbot: Certbot is a convenient tool that can be used to automatically obtain or renew an SSL certificate from Let’s Encrypt. To install it, insert:

sudo apt update
sudo apt install certbot python3-certbot-nginx

• Run Certbot to perform the SSL certificate installation:

sudo certbot --nginx -d yourdomain.com

• Configure the BTCPay server for the newly obtained SSL. To do this, access the web interface of your BTCPay server through HTTPS. Log in to your BTCPay account and go to the account settings. Updated the “Server URL” and set your domain with the "https://" prefix. Save your changes and restart BTCPay services
• Since Let’s Encrypt certificates are only valid for 90 days, it’s a useful practice to set up an autorenewal for them in the Certbot. Certbot does it through a cron job. To check this:

sudo crontab -l

Find the Certbot renewal job. It’s you don’t add it on your own:

sudo certbot renew --quiet

• Test Your HTTPS Setup. For this, access your server through the secure URL. The connection must be secure and the SSL certification valid.

Step 5: Accessing the BTCPay Server Web Interface

Go to https://btcpay.example.com. Here you can register your admin account if you haven’t done it yet. After that, new user registration will be disabled unless you want to enable it again. Wait until the nodes are synched (you can see it in the bottom-right corner). Then, feel free to explore the interface and the features of BTCPay.​

Step 6: Managing Your BTCPay Server

The first thing you’ll need to do is to create a store. Click the corresponding button in the interface. A store is responsible for receiving payments.

Afterwards, you’ll have to set up a wallet. Add one that already exists or create one on BTCPay.

You can choose either between a hot wallet where private keys are stored on the server which is convenient but more vulnerable to hacking or a watch-only wallet that provides a higher level of security since private keys are deleted from the server and stored externally.

Then you can choose out of 4 address types.​

The last thing you have to do is to set up a lightning node. Here you can either use the BTCPay internal lightning node or use a custom lightning mode.

Conclusion

BTCPay is a great solution in case you want to add cryptocurrency payments to your e-commerce store. We hope that this guide was comprehensive enough and that now you have a working BTCPay account configured. Thank you for your attention, stay tuned.