Codakey
Play
← Back to btcpayserver

How to Deploy & Use btcpayserver

BTCPay Server Deployment and Usage Guide

1. Prerequisites

System Requirements

  • Operating System: Linux (Ubuntu 20.04+ recommended), Windows, or macOS
  • Runtime: .NET 8.0 SDK and Runtime
  • Database: PostgreSQL (version 10+) or SQLite (for development)
  • Bitcoin Node: Bitcoin Core (optional but recommended for full functionality)
  • Lightning Network: Optional support for LND, Core Lightning (CLN), Eclair, or Phoenix
  • Reverse Proxy: NGINX or Apache (for production deployments)
  • Hardware: Minimum 2GB RAM, 100GB+ storage for Bitcoin node (if running full node)

Accounts & Services

  • Bitcoin wallet (self-custodial recommended)
  • Domain name (for production deployments)
  • SSL certificate (Let's Encrypt recommended)
  • Email service (for notifications, optional)

2. Installation

Option A: Docker Deployment (Recommended)

# Clone the repository
git clone https://github.com/btcpayserver/btcpayserver.git
cd btcpayserver

# Using Docker Compose (includes Bitcoin node, PostgreSQL, and NGINX)
docker-compose up -d

Option B: Manual Installation

# Clone the repository
git clone https://github.com/btcpayserver/btcpayserver.git
cd btcpayserver

# Install .NET 8.0 SDK (Ubuntu example)
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
sudo apt-get update
sudo apt-get install -y dotnet-sdk-8.0

# Install PostgreSQL
sudo apt-get install -y postgresql postgresql-contrib

# Create database
sudo -u postgres psql -c "CREATE DATABASE btcpayserver;"
sudo -u postgres psql -c "CREATE USER btcpayserver WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE btcpayserver TO btcpayserver;"

Option C: Third-Party Hosting

If you don't want to self-host, consider third-party hosting providers that offer managed BTCPay Server instances.

3. Configuration

Environment Variables

Create a .env file or set environment variables:

# Database configuration
CONNECTIONSTRING=UserID=btcpayserver;Password=your_password;Host=localhost;Port=5432;Database=btcpayserver

# Bitcoin configuration (optional)
BTCPAY_BTCEXPLORERURL=http://localhost:24444/
BTCPAY_BTCNODEENDPOINT=localhost:43782

# General settings
BTCPAY_HOST=https://yourdomain.com
BTCPAY_ROOTPATH=/  # Set if hosting in subdirectory

# Email configuration (optional)
BTCPAY_SMTPHOST=smtp.gmail.com
BTCPAY_SMTPPORT=587
BTCPAY_SMTPUSER=your_email@gmail.com
BTCPAY_SMTPPASSWORD=your_password
BTCPAY_SMTPUSESSL=true

Configuration Files

Main configuration is in BTCPayServer/appsettings.json or BTCPayServer/appsettings.Development.json:

{
  "Database": {
    "ConnectionString": "UserID=btcpayserver;Password=your_password;Host=localhost;Port=5432;Database=btcpayserver"
  },
  "Services": {
    "ExternalServices": {
      "Bitcoin": {
        "Endpoint": "http://localhost:43782",
        "Explorer": "http://localhost:24444/"
      }
    }
  }
}

Lightning Network Configuration

Configure Lightning nodes through the web interface after installation or via API:

# Example LND configuration via API
curl -X POST https://your-btcpay-server/api/v1/stores/{storeId}/lightning/BTC \
  -H "Authorization: Token your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionString": "type=lnd-rest;server=https://localhost:8080/;macaroon=your_macaroon;allowinsecure=true"
  }'

4. Build & Run

Development Environment

# Restore dependencies
dotnet restore

# Build the project
dotnet build

# Run with development settings
dotnet run --project BTCPayServer --configuration Debug

# Or using the launch profile
dotnet run --launch-profile BTCPayServer.Development

Production Build

# Publish for production
dotnet publish -c Release -o ./publish

# Run published application
cd ./publish
dotnet BTCPayServer.dll --urls=http://0.0.0.0:8080

Docker Build

# Build custom Docker image
docker build -t btcpayserver:latest .

# Run with custom configuration
docker run -p 8080:8080 \
  -e CONNECTIONSTRING="UserID=btcpayserver;Password=your_password;Host=db;Port=5432;Database=btcpayserver" \
  -v /path/to/data:/app/data \
  btcpayserver:latest

5. Deployment

Option A: Docker Compose (Production)

# docker-compose.production.yml
version: '3'
services:
  btcpayserver:
    image: btcpayserver/btcpayserver:latest
    restart: always
    ports:
      - "80:80"
      - "443:443"
    environment:
      CONNECTIONSTRING: UserID=btcpayserver;Password=${DB_PASSWORD};Host=postgres;Port=5432;Database=btcpayserver
      BTCPAY_HOST: https://yourdomain.com
    volumes:
      - btcpayserver_data:/datadir
      - /etc/letsencrypt:/etc/letsencrypt:ro
    depends_on:
      - postgres
      - bitcoind

  postgres:
    image: postgres:13
    restart: always
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: btcpayserver
    volumes:
      - postgres_data:/var/lib/postgresql/data

  bitcoind:
    image: btcpayserver/bitcoin:latest
    restart: always
    volumes:
      - bitcoin_data:/data

volumes:
  btcpayserver_data:
  postgres_data:
  bitcoin_data:

Option B: Kubernetes

# btcpayserver-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: btcpayserver
spec:
  replicas: 2
  selector:
    matchLabels:
      app: btcpayserver
  template:
    metadata:
      labels:
        app: btcpayserver
    spec:
      containers:
      - name: btcpayserver
        image: btcpayserver/btcpayserver:latest
        env:
        - name: CONNECTIONSTRING
          valueFrom:
            secretKeyRef:
              name: btcpay-secrets
              key: connectionstring
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: btcpayserver-service
spec:
  selector:
    app: btcpayserver
  ports:
  - port: 80
    targetPort: 80
  type: LoadBalancer

Option C: Traditional Linux Server

# Set up NGINX reverse proxy
sudo apt-get install -y nginx
sudo systemctl enable nginx

# Configure NGINX
sudo nano /etc/nginx/sites-available/btcpayserver

# NGINX configuration example
server {
    listen 80;
    server_name yourdomain.com;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        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 $scheme;
    }
}

# Enable SSL with Let's Encrypt
sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com

Deployment Platforms

  • Self-hosted: Docker, Kubernetes, traditional VPS
  • Cloud: AWS, Azure, Google Cloud, DigitalOcean (marketplace image available)
  • Specialized: Raspberry Pi (for low-volume use cases)
  • One-click: Some hosting providers offer BTCPay Server as a one-click app

6. Troubleshooting

Common Issues

1. Database Connection Errors

# Check PostgreSQL is running
sudo systemctl status postgresql

# Test connection
psql -U btcpayserver -h localhost -d btcpayserver

# Check connection string format
# Correct: UserID=btcpayserver;Password=password;Host=localhost;Port=5432;Database=btcpayserver

2. Bitcoin Node Synchronization

# Check Bitcoin Core status
bitcoin-cli getblockchaininfo

# Check NBXplorer logs
docker logs btcpayserver_nbxplorer_1

# Ensure ports are open
# Bitcoin P2P: 8333 (mainnet), 18333 (testnet)
# RPC: 8332 (mainnet), 18332 (testnet)

3. Lightning Network Issues

# Test Lightning node connection
lncli getinfo

# Check BTCPay Server Lightning configuration
# Verify connection string format:
# type=lnd-rest;server=https://localhost:8080/;macaroon=admin.macaroon;allowinsecure=true

4. Permission Errors

# Check file permissions for data directory
sudo chown -R www-data:www-data /var/lib/btcpayserver
sudo chmod -R 755 /var/lib/btcpayserver

# For Docker deployments
docker exec btcpayserver ls -la /datadir

5. SSL/TLS Certificate Issues

# Renew Let's Encrypt certificates
sudo certbot renew

# Check certificate validity
openssl s_client -connect yourdomain.com:443 -servername yourdomain.com

# For Docker, ensure certificates are mounted correctly
volumes:
  - /etc/letsencrypt:/etc/letsencrypt:ro

6. API Authentication Problems

# Generate new API key in Settings > Access Tokens
# Or via command line:
curl -X POST https://your-btcpay-server/api/v1/api-keys \
  -u "your_email:your_password" \
  -H "Content-Type: application/json" \
  -d '{"label": "cli-token", "permissions": ["btcpay.store.canviewinvoices"]}'

Logs and Debugging

# View application logs
docker logs btcpayserver_btcpayserver_1

# Or for manual installation
journalctl -u btcpayserver -f

# Enable debug logging
export LOG_LEVEL=debug
dotnet run --project BTCPayServer

# Check specific service logs
docker logs btcpayserver_nbxplorer_1 --tail 100

Performance Issues

  1. High Memory Usage: Consider increasing swap space or upgrading RAM
  2. Slow Synchronization: Use pruned node or increase dbcache in Bitcoin Core
  3. Database Slowdown: Add indexes or upgrade PostgreSQL configuration
  4. Network Issues: Check firewall settings and port forwarding

Getting Help

Remember to always backup your wallet seeds, database, and configuration files before making significant changes to your deployment.

← Project overviewView alternatives to btcpayserver →