How to Set Up BTCPay Server on Ubuntu 22.04/20.04 with Docker

Last Updated: October 1st, 2022

BTCPay Server is an open-source, self-hosted cryptocurrency payment processor. With BTCPay Server, you don’t need to pay fees to a third-party payment processor, and since it’s peer-to-peer payment, it’s resistant to censorship. This tutorial will be showing you how to set up BTCPay Server on Ubuntu.

BTCPay Server Features

• Your own Bitcoin payment processor with no risk of third-party account closure.
• Eliminates unreasonable transaction processing fees set by corporate processors.
• Native integration with major eCommerce platforms including Magento, Shopify, WooCommerce, Joomla Virtuemart, Prestashop, and Shopware.
• Supports an unlimited amount of users and stores.
• Full support for the Bitcoin Lightning Network and various altcoins.
• Direct integration with QuickBooks Online Accounting, powerful APIs, and custom plugin environments.

Note: While BTCPay Server removes third-party payment processor margins, standard network mining or transaction fees still apply. These network overheads can be significantly reduced by implementing a Lightning node and using the internal payout processor tool.

Server Requirements

• At least 2 CPU cores and 4GB RAM.
• A minimum of 600 GB disk space for blockchain data storage.

We will be using the BTCPay Docker implementation, which greatly simplifies the deployment architecture. Manual configuration is explicitly discouraged for production environments.

Step 1: Install Docker on Ubuntu Server

To ensure we are utilizing the latest stable build, install Docker from the official upstream repository. Log into your server via SSH, and execute the following command to declare the Docker APT repository:

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 official Docker repository GPG key to verify package integrity:

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

Install system dependencies required for handling secure APT HTTPS transports:

sudo apt install apt-transport-https ca-certificates

Update the package indices and install Docker Community Edition (docker-ce):

sudo apt update
sudo apt install docker-ce

Verify that the service engine is running, and enable it to start automatically at system boot time:

systemctl status docker
sudo systemctl enable docker

Step 2: Install and Start the BTCPay Docker Container

This deployment must be configured inside a root shell environment. Switch to the root user:

sudo su -

Install Git and clone the official BTCPay Server configuration tree:

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

Configure the environment flags used by the generation tool script. Make sure to replace btcpay.example.com with your target domain name:

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

Run the initialization setup script to generate configurations and build your stack containers:

. ./btcpay-setup.sh -i

Verify that the host system daemon launched the application engine successfully:

sudo systemctl status btcpayserver.service

By default, the internal application container is isolated and does not bind custom web routing definitions to the host network interface. To expose its application port, open the auto-generated compose configuration file:

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

Locate the btcpayserver: runtime configuration block and explicitly append the ports directive mapping array:

    ports:
    - "49392:49392"

Save configurations and restart your application daemon to instantiate network port maps:

sudo systemctl restart btcpayserver
sudo docker ps

Step 3: Configure Nginx Reverse Proxy

Install the standard Nginx web server engine layer:

sudo apt install -y nginx

Create a dedicated virtual host routing mapping configuration:

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

Populate the file with the following configuration block. Ensure your server_name match definitions use your real target hostname:

map $http_x_forwarded_proto $proxy_x_forwarded_proto {
  default $http_x_forwarded_proto;
  ''      $scheme;
}

map $http_x_forwarded_port $proxy_x_forwarded_port {
  default $http_x_forwarded_port;
  ''      $server_port;
}

map $http_upgrade $proxy_connection {
  default upgrade;
  '' close;
}

server_names_hash_bucket_size 128;
server_tokens off;

map $scheme $proxy_x_forwarded_ssl {
  default off;
  https on;
}

gzip_types text/plain text/css application/javascript application/json application/x-javascript text/xml application/xml application/xml+rss text/javascript;

proxy_http_version 1.1;
proxy_buffering off;
proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $proxy_connection;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $proxy_x_forwarded_proto;
proxy_set_header X-Forwarded-Ssl $proxy_x_forwarded_ssl;
proxy_set_header X-Forwarded-Port $proxy_x_forwarded_port;
proxy_buffer_size          128k;
proxy_buffers              4 256k;
proxy_busy_buffers_size    256k;
client_header_buffer_size 500k;
large_client_header_buffers 4 500k;
proxy_set_header Proxy "";

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

        access_log /var/log/nginx/btcpay.access;
        error_log /var/log/nginx/btcpay.error;
        client_max_body_size 100M;

        location / {
                proxy_pass http://127.0.0.1:49392;
        }

        location /rtl/ {
                proxy_pass http://127.0.0.1:3000/rtl/;
        }
}

Validate your web engine syntax mappings and apply changes cleanly:

sudo nginx -t
sudo systemctl reload nginx

Step 4: Enable HTTPS

To encrypt your cryptocurrency transactional payloads, provision a secure Let's Encrypt TLS certificate layer using the Certbot module package:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d btcpay.example.com

Step 5: Using the BTCPay Server Web Interface

Open your web browser and load your secure control dashboard at https://btcpay.example.com to configure your administrative user credentials. Once this initialization setup completes, public visitor sign-up registrations will lock down automatically.

Look at the sync indicator in the lower control pane. Before provisioning live store integrations or processing active wallet actions, allow your host process to finish building and matching blockchain sync values.

Step 6: Provisioning Stores, Wallets, and Lightning Features

• Select Create Store inside the control workspace to declare your collection profile matrix.
• Click Set up a wallet to hook your asset configurations. You can connect tracking structures securely by picking a Watch-only wallet using standard Segwit tracking derivations.
• Ensure you back up your auto-generated backup phrase mappings safely on non-digital layouts.
• To deploy immediate layer-2 pathways, access the Set up a lightning node configuration pane and map the connection directly onto the built-in Internal node system profile.

How to Upgrade BTCPay Server

When software updates launch, access your root system terminal layer and trigger the explicit update shell sequence manually:

btcpay-update.sh

Because code recreation passes will rewrite auto-generated layouts, re-open the compose matrix script to verify your custom loop maps are still matching:

sudo nano /root/btcpayserver-docker/Generated/docker-compose.generated.yml

Ensure your structural port forwarding blocks are present in the btcpayserver definition:

    ports:
    - "49392:49392"

Save alterations and reload the underlying container service tree safely:

sudo systemctl restart btcpayserver