How to Install BTCPay Server on Ubuntu

BTCPay Server is a free, open-source cryptocurrency payment processor that allows merchants and individuals to accept Bitcoin and other cryptocurrencies without relying on third-party payment processors. Unlike traditional payment gateways that charge fees and may freeze accounts, BTCPay Server gives you complete control over your cryptocurrency transactions while maintaining your privacy and security.

This self-hosted solution has gained tremendous popularity among businesses, developers, and cryptocurrency enthusiasts who value financial sovereignty. With BTCPay Server, you become your own payment processor, eliminating intermediaries and reducing costs significantly.

Table of Contents

Why Choose BTCPay Server for Cryptocurrency Payments

Key Benefits of Self-Hosting BTCPay Server

Complete Financial Control: When you install BTCPay Server on your own Ubuntu server, you maintain full custody of your funds. There’s no third party that can freeze your account or withhold your payments. This level of control is particularly valuable for businesses operating in regions with strict financial regulations.
Zero Transaction Fees: Traditional payment processors typically charge 2-4% per transaction. BTCPay Server eliminates these fees entirely – you only pay standard Bitcoin network fees, which are typically much lower.
Enhanced Privacy: Your payment data stays on your server. Unlike hosted solutions that may track and analyze your transaction patterns, BTCPay Server ensures your business data remains private.
Customization Freedom: The open-source nature allows you to modify the software according to your specific business needs. You can integrate custom features, modify the user interface, and extend functionality as required.

BTCPay Server vs Traditional Payment Processors

Traditional payment processors like PayPal or Stripe offer convenience but come with significant drawbacks: high fees, account restrictions, chargebacks, and limited cryptocurrency support. BTCPay Server addresses these issues by providing direct peer-to-peer transactions with finality – once a Bitcoin payment is confirmed, it cannot be reversed.

System Requirements for BTCPay Server Installation

Minimum Hardware Requirements

Before you install BTCPay Server on Ubuntu, ensure your system meets these minimum requirements:

RAM: At least 2GB RAM, but 4GB or more is recommended for optimal performance. If you’re planning to run a full Bitcoin node, consider 8GB RAM for better stability.

Storage: Minimum 500GB of available disk space. If you’re running without pruning, you’ll need at least 1TB for the full Bitcoin blockchain. SSD storage is highly recommended for faster synchronization and better performance.

CPU: Any modern dual-core processor will work, but quad-core is preferred for handling multiple cryptocurrency networks simultaneously.

Network: Stable internet connection with sufficient bandwidth for blockchain synchronization. The initial sync can consume several hundred gigabytes of data.

Supported Ubuntu Versions

BTCPay Server officially supports several Ubuntu versions:

Ubuntu 24.04 LTS (Recommended)
Ubuntu 22.04 LTS
Ubuntu 18.04 LTS (Limited support)

We strongly recommend using Ubuntu 22.04 LTS as it provides the best compatibility and long-term support.

Network and Domain Prerequisites

Domain Name: You’ll need a domain name pointing to your server’s IP address. This is essential for SSL certificate generation and proper functionality.

Port Access: Ensure ports 80, 443, and 9735 (for Lightning Network) are accessible from the internet. If you’re behind a firewall or using a VPS, configure these ports appropriately.

Pre-Installation Setup

Setting Up Your Ubuntu Server

Start by updating your Ubuntu system to ensure you have the latest security patches and package versions:

sudo apt update && sudo apt upgrade -y

Install essential packages that will be needed during the installation process:

sudo apt install curl wget git unzip -y

Create a non-root user with sudo privileges if you haven’t already:

sudo adduser btcpay
sudo usermod -aG sudo btcpay

Configuring Domain Name and DNS

Set up an A record in your DNS provider pointing to your server’s IP address. For example, if your domain is example.com and you want BTCPay Server accessible at btcpay.example.com, create:

Type: A
Host: btcpay
Value: Your_Server_IP_Address
TTL: 3600

DNS propagation can take anywhere from a few minutes to 24 hours, so plan accordingly.

Essential Security Configurations

Firewall Setup: Configure UFW (Uncomplicated Firewall) to restrict access:

sudo ufw allow ssh
sudo ufw allow 80
sudo ufw allow 443
sudo ufw allow 9735
sudo ufw enable

SSH Security: Disable password authentication and use SSH keys for enhanced security. Edit /etc/ssh/sshd_config and set PasswordAuthentication no.

Method 1: Installing BTCPay Server with Docker (Recommended)

The Docker installation method is the most reliable and recommended approach for installing BTCPay Server on Ubuntu. This method handles all dependencies automatically and provides easier updates and maintenance.

Installing Docker and Docker Compose

First, install Docker using the official Docker repository for better compatibility:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \
https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-compose
sudo systemctl enable --now docker

Add your user to the docker group to run Docker commands without sudo:

sudo usermod -aG docker $USER

Log out and back in for the group changes to take effect.

Cloning BTCPay Server Repository

Switch to the root user for the installation process:

sudo su -

Create a dedicated directory and clone the BTCPay Server Docker repository:

mkdir -p ~/btcpay
cd ~/btcpay
git clone https://github.com/btcpayserver/btcpayserver-docker
cd btcpayserver-docker

Configuring Environment Variables

The installation requires several environment variables to be configured properly. These variables determine how BTCPay Server will operate and what features will be enabled.

Setting Up Your Domain

Replace btcpay.example.com with your actual domain name:

export BTCPAY_HOST="btcpay.example.com"
export NBITCOIN_NETWORK="mainnet"

For testnet deployment (useful for testing), use:

export NBITCOIN_NETWORK="testnet"

Choosing Your Cryptocurrency Support

BTCPay Server supports multiple cryptocurrencies. For Bitcoin-only setup:

export BTCPAYGEN_CRYPTO1="btc"

For multiple cryptocurrencies, you can add:

export BTCPAYGEN_CRYPTO2="ltc"  # Litecoin
export BTCPAYGEN_CRYPTO3="eth"  # Ethereum

Lightning Network Configuration

Enable Lightning Network support with Core Lightning (CLN):

export BTCPAYGEN_LIGHTNING="clightning"

Alternatively, you can use LND:

export BTCPAYGEN_LIGHTNING="lnd"

Additional Configuration Options:

export BTCPAYGEN_REVERSEPROXY="nginx"
export BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage-s"
export BTCPAY_ENABLE_SSH=true

The opt-save-storage-s fragment enables blockchain pruning, which significantly reduces storage requirements to approximately 60GB instead of the full 500GB+ blockchain.

Running the BTCPay Setup Script

Execute the setup script using the source command (the leading dot is crucial):

. ./btcpay-setup.sh -i

This script will automatically:

Install and configure all necessary Docker containers
Set up SSL certificates using Let’s Encrypt
Configure the reverse proxy (Nginx)
Start the blockchain synchronization process
Create systemd services for automatic startup

The initial setup and blockchain synchronization can take several hours or even days, depending on your internet connection and whether you’re using pruning.

Method 2: Manual Installation of BTCPay Server

Warning: Manual installation is not recommended for production use unless you have extensive technical expertise. This method is primarily for educational purposes and development environments.

Installing Bitcoin Core

Download and install Bitcoin Core:

BITCOIN_VERSION="0.19.1"
BITCOIN_URL="https://bitcoin.org/bin/bitcoin-core-0.19.1/bitcoin-0.19.1-x86_64-linux-gnu.tar.gz"
BITCOIN_SHA256="5fcac9416e486d4960e1a946145566350ca670f9aaba99de6542080851122e4c"

cd /tmp
wget -O bitcoin.tar.gz "$BITCOIN_URL"
echo "$BITCOIN_SHA256 bitcoin.tar.gz" | sha256sum -c - && \
mkdir bin && \
sudo tar -xzvf bitcoin.tar.gz -C /usr/local/bin --strip-components=2 \
"bitcoin-$BITCOIN_VERSION/bin/bitcoin-cli" "bitcoin-$BITCOIN_VERSION/bin/bitcoind"
rm bitcoin.tar.gz

Installing .NET 8.0 SDK

BTCPay Server is built with .NET, so install the SDK:

wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

sudo apt-get update
sudo apt-get install -y apt-transport-https
sudo apt-get install -y dotnet-sdk-8.0

# Verify installation
dotnet --version

Installing NBXplorer

NBXplorer is a Bitcoin blockchain explorer that BTCPay Server uses to track transactions:

cd ~
git clone https://github.com/dgarage/NBXplorer
cd NBXplorer
git checkout latest
./build.sh

Installing BTCPay Server Components

Clone and build the main BTCPay Server application:

cd ~
git clone https://github.com/btcpayserver/btcpayserver
cd btcpayserver
git checkout latest
./build.sh

Running All Services

Start the services in separate terminal sessions or use screen/tmux:

Start Bitcoin Core:

bitcoind

Start NBXplorer:

cd ~/NBXplorer
./run.sh --dbtrie

Start BTCPay Server:

cd ~/btcpayserver
./run.sh --port 8080 --bind 0.0.0.0

Your BTCPay Server will be accessible at http://your-server-ip:8080.

Post-Installation Configuration

Accessing Your BTCPay Server Interface

Once installation is complete and the blockchain has finished synchronizing, access your BTCPay Server through your configured domain (e.g., https://btcpay.example.com). The setup process automatically configures SSL certificates, so you should see a secure connection.

On first access, you’ll be prompted to create an administrator account. Choose a strong password and enable two-factor authentication for enhanced security.

Setting Up Your First Store

Navigate to the “Stores” section and create your first store:

Store Name: Choose a descriptive name for your business
Store Website: Enter your main website URL
Default Currency: Set your preferred fiat currency for pricing
Price Source: Select a reliable exchange for price conversion

Configuring Payment Methods

In your store settings, configure the cryptocurrencies you want to accept:

On-chain Bitcoin: Configure your Bitcoin wallet for direct payments
Lightning Network: Set up Lightning channels for instant micropayments
Additional Cryptocurrencies: Enable Litecoin, Ethereum, or other supported coins as needed

Troubleshooting Common Installation Issues

Docker-Related Problems

Container Fails to Start: Check Docker logs using docker-compose logs to identify specific errors. Common issues include insufficient disk space or network connectivity problems.

Permission Errors: Ensure your user is in the docker group and has proper file permissions in the BTCPay directory.

SSL Certificate Issues

Let’s Encrypt Failures: Verify that your domain correctly points to your server and ports 80 and 443 are accessible from the internet. DNS propagation delays can cause certificate generation to fail initially.

Blockchain Synchronization Problems

Slow Synchronization: Bitcoin blockchain sync can take 24-72 hours on initial setup. Monitor progress through the BTCPay Server interface. Consider using pruning to reduce storage requirements.

Sync Stuck: If synchronization appears stuck, restart the Bitcoin container: docker-compose restart bitcoind

Security Best Practices

Regular Updates: Keep your Ubuntu system and BTCPay Server updated. The Docker installation method makes updates straightforward with btcpay-update.sh.

Backup Strategy: Regularly backup your BTCPay Server data, including wallet seeds, store configurations, and database. Store backups securely offline.

Network Security: Use a VPN for administrative access, implement fail2ban for SSH protection, and consider setting up a firewall whitelist for admin access.

Wallet Security: Use hardware wallets for larger amounts and implement proper key management practices. Never store large amounts in hot wallets connected to your BTCPay Server.

Maintenance and Updates

BTCPay Server requires regular maintenance to ensure optimal performance and security. With the Docker installation, updates are simplified through provided scripts:

btcpay-update.sh

Monitor system resources regularly and ensure adequate disk space for blockchain growth. Set up monitoring tools to track server performance and receive alerts for critical issues.

Frequently Asked Questions (FAQs)

Q: How long does it take to install BTCPay Server on Ubuntu?
A: The installation process itself takes 30-60 minutes, but the initial blockchain synchronization can take 24-72 hours depending on your internet connection and whether you’re using pruning mode.

Q: Can I install BTCPay Server on a VPS with limited storage?
A: Yes, use the pruning option (opt-save-storage-s) which reduces storage requirements to approximately 60GB instead of the full 500GB+ blockchain. This is suitable for most VPS configurations.

Q: Is it safe to run BTCPay Server on a home server?
A: While possible, running BTCPay Server at home requires careful attention to network security, dynamic IP management, and reliable internet connectivity. VPS hosting is generally recommended for production use.

Q: What cryptocurrencies does BTCPay Server support besides Bitcoin?
A: BTCPay Server supports numerous cryptocurrencies including Litecoin, Ethereum, Monero, Zcash, and many others. You can configure multiple cryptocurrencies during installation or add them later.

Q: Can I migrate from a hosted BTCPay Server solution to self-hosted?
A: Yes, BTCPay Server provides migration tools and documentation for moving from hosted solutions to your own Ubuntu server. The process involves exporting store configurations and setting up the new instance with your existing data.