Deployment FAQ
This document covers the most common questions, errors, and issues you may encounter prior and during the installation of the software. For a detailed list of deployments method and instructions for each, please see Deployment page.
Here are common questions about installation, regardless of the deployment method.
BTCPay is a 100% free and open-source software. We do not charge you anything. However, to run it, you should host it. You can run it as a self-hosted solution on your own local server, or use a cloud hosting provider, which is what a majority of users do. Advanced users can run BTCPay on their own hardware Visit our Deployment Page to see various ways in which you can run BTCPay. If you do not wish to host your own server, you should use a free host. If you prefer to have control over your node and additional features, you can use a cloud solution, which goes from 5$ to 65$ /month depending on the provider you choose.
If you would like to run Bitcoin and Lightning Network nodes, the minimal requirements are :
2GB Ram
80 GB of storage with enabled pruning​
Docker
For beginners, we strongly recommend the web-deployment if you want a self-hosted solution or a third-party host​
If you're going to add more than one crypto coin, you need to expand the storage according to that coin(s) blockchain size.
Please see Deployment page for comparison of different installation methods and choose the one that suits your needs and skill level the most.
Yes, you can. Check our the Hardware Deployment page for detailed instructions.
Yes. BTCPay is not limited to the documented deployment methods. You can use whichever hosting solution you prefer, that fits the minimal requirements.
On a self-hosted BTCPay, the unlimited amount of users and stores can be attached. That's why there are users who opened their servers for others to use. Most of them are community-driven and free. See this list of third-party BTCPay hosts​
When you deploy your BTCPay Server, you should first register a user (during server synchronization). This user is automatically the server admin. If your BTCPay only shows Login in the header menu, and you are unable to register the first user after initial deployment, someone else has registered on your server as the admin. Although this is unlikely to occur (the user would need to know and watch your BTCPay domain name), they had access to your ssh private keys, thus you should redeploy a new server for security reasons.
First, you need to make sure that btcpayserver and docker is not running
sudo su -btcpay-down.shsystemctl stop docker
Now, you need to format your drive. If you already did you can skip this step.
# Step 1: Unplug the drivelsblk​# Step 2: Plug the drivelsblk
The second lsblk should show the drive you just plugged in. (of TYPE disk) Make sure you don't make a mistake as the next command will erase all data on this disk.
For the sake of the example, let's suppose it has the NAME /dev/sdd.
# Save the name in a variableDEVICE_NAME="/dev/sdd"# Set the partition namePARTITION_NAME="/dev/sdd1"
Now we can partition the disk and format the partition:
echo "Partitioning the external drive $DEVICE_NAME..."### DANGER ZONE ###(echo o # Create a new empty DOS partition tableecho n # Add a new partitionecho p # Primary partitionecho 1 # Partition numberecho # First sector (Accept default: 1)echo # Last sector (Accept default: varies)echo w # Write changes) | fdisk ${DEVICE_NAME}partprobe ${DEVICE_NAME}while ! lsblk $PARTITION_NAME &> /dev/null; dosleep 1donemkfs.ext4 -F "$PARTITION_NAME"
Then we need to mount the partition on the linux filesystem.
# Mounting the partitionMOUNT_DIR="/mnt/external"mkdir "$MOUNT_DIR"mount -o defaults,noatime "$PARTITION_NAME" "$MOUNT_DIR"​# Make sure the partition exists at the next reboot, we use UUID in case# the partition name is different in the next rebootif ! grep -qF "$MOUNT_DIR" /etc/fstab; thenUUID="$(sudo blkid -s UUID -o value $PARTITION_NAME)"echo "UUID=$UUID $MOUNT_DIR ext4 defaults,noatime,nofail 0 2" >> /etc/fstabfi
Then, we need to make sure that docker not start before the mount.
MOUNT_UNIT="$(systemd-escape --path "$MOUNT_DIR").mount"docker_service="/lib/systemd/system/docker.service"if ! grep -qF "After=$MOUNT_UNIT" "$docker_service"; thensed -i "s/After=/After=$MOUNT_UNIT /g" "$docker_service"fi
Now, imagine you want to put all the docker volume data on the previous partition
DOCKER_VOLUMES="/var/lib/docker/volumes"# Copy all the data from our volume to the mount directory (this can take a while)cp -a -r "$DOCKER_VOLUMES/." "$MOUNT_DIR"# Make the folder a mountpointrm -rf "$DOCKER_VOLUMES"mkdir -p "$DOCKER_VOLUMES"mount --bind "$MOUNT_DIR" "$DOCKER_VOLUMES"# Make sure the mountpoint is mounted after rebootif ! grep -qF "$DOCKER_VOLUMES" /etc/fstab; thenecho "$MOUNT_DIR $DOCKER_VOLUMES none bind,nobootwait 0 2" >> /etc/fstabfi
Now restart docker and btcpayserver
systemctl start dockerbtcpay-up.sh
Note: We use mount bind instead of symbolic link because docker would complain when running docker volume rm.
The instructions below are valid for Docker deployments:
Run setup as described in btcpayserver-docker up until
. ./btcpay-setup.sh -iCreate
bitcoin.custom.ymlin thedocker-compose-generator/docker-fragments/folder.
version: "3"​services:btcpayserver:environment:BTCPAY_CHAINS: "btc"BTCPAY_BTCEXPLORERURL: http://nbxplorer:32838/nbxplorer:environment:NBXPLORER_CHAINS: "btc"NBXPLORER_BTCRPCURL: http://host.docker.internal:43782/NBXPLORER_BTCNODEENDPOINT: host.docker.internal:39388volumes:- "localBitcoinfolder:/root/.bitcoin"
Replace:
43782with your bitcoin node's configured RPC portReplace:
39388with your bitcoin node's configured p2p portReplace
localBitcoinfolderwith the path to your bitcoin data folder
If you are running on linux, due to a limitation of docker, you will also need to do the following:
Run
ip route | grep docker0 | awk '{print $9}'Add the following at the end of the
bitcoin.custom.ymlfile, replacing$DOCKER_HOST_IPwith the result of the previous command.extra_hosts:- "host.docker.internal:$DOCKER_HOST_IP"
Run
BTCPAYGEN_EXCLUDE_FRAGMENTS="bitcoin"Run
BTCPAYGEN_ADDITIONAL_FRAGMENTS="$BTCPAYGEN_ADDITIONAL_FRAGMENTS"Run
. ./btcpay-setup.sh -i
Tor is activated by default on the docker deployment.
That's really easy: just log in your instance with SSH, and enter the root/btcpayserver-docker directory as root. There, type the two following command lines:
root/btcpayserver-docker $ BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;opt-add-tor"root/btcpayserver-docker $ . btcpay-setup.sh -i
Then wait a few minutes for the server to restart, and you're done!
Tor for BTCPay server is intended more as an improvement of the setup process, and allows for more flexibility for hosting on one's own device at home or in an office.
Having Tor activated would allow for simpler, plug-and-play usage of BTCPay, as it suppress the need for the following configuration steps:
Opening multiple ports on the firewall
Configuring the NAT for port redirection to your device on your local network
Setting up a DNS entry to get a HTTPS certificate
Having a fixed IP for Lightning
While these steps are usually not a problem when BTCPay is hosted on a VPS, it can be difficult to solve for non-technical users on home or office networks.
Tor just solves all these issues in one shot, all you have to do is plug your device on the local network. It is especially useful for POS application.
But if you're looking for perfect privacy and security, activating Tor with your BTCPay just won't do it.
Tor is a really tricky software to use for developers, as the slightest mistake can tear down the anonymity it provides. As BTCPay is evolving into a rather complex service and adding more and more plugins, even if we tried to route all this traffic through Tor, we couldn't guarantee that there would never be leaks of data in clear.
We think that the illusion of security is more dangerous that no security, or at least security we know is imperfect. So be aware that activating Tor doesn't prevent others to connect to your instance website, your bitcoin or lightning node in clear, it doesn't make you anonymous at all.
If you want to know more about the philosophy behind all this, you can read our article on Medium.
To see the .onion address of your BTCPay instance without accessing it through the clearnet and clicking the Tor logo in top left corner, apply the following command:
tail /var/lib/docker/volumes/generated_tor_servicesdir/_data/BTCPayServer/hostname
In BTCPay, various options are activated through environment variables. You can modify or delete any of these options using command lines by exporting the new value with export {environment variable}="{value}" and then running . ./btcpay-setup.sh -i again.
For example, let's say I want to deactivate Tor for my BTCPay server:
# Login as rootsudo su -​# Go to the root/btcpayserver-docker directorycd /root/btcpayserver-docker​# Print the complete list of options that you are running (for the sake of the demonstration, let's say that beside Tor you have pruning mode activated too)echo $BTCPAYGEN_ADDITIONAL_FRAGMENTSopt-save-storage-s;opt-add-tor​# Export the BTCPAYGEN_ADDITIONAL_FRAGMENTS variable without opt-add-torexport BTCPAYGEN_ADDITIONAL_FRAGMENTS="opt-save-storage-s"​# Run btcpay-setup.sh. btcpay-setup.sh -i​exit
If you need to figure out which environment variable you need to modify, have a look at this list.
Building on the section above, this is how you configure BTCPay to use testnet instead of the default mainnet:
# Export the NBITCOIN_NETWORK variable switching to testnetexport NBITCOIN_NETWORK="testnet"​# Run btcpay-setup.sh for the change to take effect. btcpay-setup.sh -i
If you just want to test things quickly without deploying everything yourself, have a look at the Try It Out section. It provides links and explanations for a BTCPay testnet instance hosted by us.
No, you need to keep your BTCPay running at all times so that your Bitcoin node stays in sync with the blockchain to verify transactions. If you only start it up every now and then, it would take a long time to catch up on verifying recent blocks, and your payments would not show up until much later.
No, BTCPay's Bitcoin core node is not exposed externally. For BTCPay purposes, it is not in the interest of the user, as it increases bandwidth requirement. BTCPay is also whitebinding connections to this port, so opening it would expose the node to potential DDoS.
Yes you can! Just make sure to use the proper configuration.
Create an extra config file for your vhost in /etc/nginx/sites-available/btcpayserver and create a symlink for this file at /etc/nginx/sites-enabled/btcpayserver
The contents of this vhost file should look like this:
server {listen 80;​root /var/www/html;index index.html index.htm index.nginx-debian.html;​# Put your domain name hereserver_name btcpay.domain.com;​# Needed for Let's Encrypt verificationlocation ~ /.well-known {allow all;}​# Force HTTP to HTTPSlocation / {return 301 https://$http_host$request_uri;}}​server {listen 443 ssl http2;​ssl on;​# SSL certificate by Let's Encrypt in this Nginx (not using Let's Encyrpt that came with BTCPay Server Docker)ssl_certificate /etc/letsencrypt/live/btcpay.domain.com/fullchain.pem;ssl_certificate_key /etc/letsencrypt/live/btcpay.domain.com/privkey.pem;​root /var/www/html;index index.html index.htm index.nginx-debian.html;​# Put your domain name hereserver_name btcpay.domain.com;​# Route everything to the real BTCPay serverlocation / {# URL of BTCPay Server (i.e. a Docker installation with REVERSEPROXY_HTTP_PORT set to 10080)proxy_pass http://127.0.0.1:10080;​proxy_set_header Host $http_host;proxy_set_header X-Forwarded-Proto $scheme;proxy_set_header X-Real-IP $remote_addr;proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;​# For websockets (used by Ledger hardware wallets)proxy_set_header Upgrade $http_upgrade;}​# Needed for Let's Encrypt verificationlocation ~ /.well-known {allow all;}}
Also, put the following in your main Nginx config file at /etc/nginx/nginx.conf:
http {​# ... # Existing stuff​# Needed to allow very long URLs to prevent issues while signing PSBTsserver_names_hash_bucket_size 128;proxy_buffer_size 128k;proxy_buffers 4 256k;proxy_busy_buffers_size 256k;client_header_buffer_size 500k;large_client_header_buffers 4 500k;http2_max_field_size 500k;http2_max_header_size 500k;​# Needed websocket support (used by Ledger hardware wallets)map $http_upgrade $connection_upgrade {default upgrade;'' close;}​}
Now test your Nginx config with service nginx configtest and reload the config with service nginx reload.
Then, you need to make sure that BTCPayServer does not try to handle HTTPS on its side, you can do this by disabling it on your BTCPayServer instance.
BTCPAYGEN_EXCLUDE_FRAGMENTS="$BTCPAYGEN_EXCLUDE_FRAGMENTS;nginx-https". btcpay-setup.sh -i
Notice: If your BTCPay Server install has more than one domain (for example WOOCOMMERCE_HOST or BTCPAY_ADDITIONAL_HOSTS) you will need to modify your config for each domain name. The example above only covers 1 domain name called btcpay.domain.com.
Shutdown BTCPay Server (after you ensure you have required backups etc) with
btcpay-down.shand cleanup the install withbtcpay-clean.sh.Change to your Base install directory
cd "$(dirname "$BTCPAY_ENV_FILE")"Delete all volumes in /var/lib/docker/volumes/ with
docker-compose -f $BTCPAY_DOCKER_COMPOSE down --vRemove other BTCPay system files with this:
rm /etc/systemd/system/btcpayserver.service && rm /etc/profile.d/btcpay-env.shGo into /usr/local/bin and remove all of the symlinks that BTCPay put in there. At the time of writing these were:
bitcoin-cli.sh -> /root/BTCPayServer/btcpayserver-docker/bitcoin-cli.shbitcoin-lncli.sh -> /root/BTCPayServer/btcpayserver-docker/bitcoin-lncli.shbtcpay-admin.sh -> /root/BTCPayServer/btcpayserver-docker/btcpay-admin.shbtcpay-clean.sh -> /root/BTCPayServer/btcpayserver-docker/btcpay-clean.shbtcpay-down.sh -> /root/BTCPayServer/btcpayserver-docker/btcpay-down.shbtcpay-restart.sh -> /root/BTCPayServer/btcpayserver-docker/btcpay-restart.shbtcpay-setup.sh -> /root/BTCPayServer/btcpayserver-docker/btcpay-setup.shbtcpay-up.sh -> /root/BTCPayServer/btcpayserver-docker/btcpay-up.shbtcpay-update.sh -> /root/BTCPayServer/btcpayserver-docker/btcpay-update.shchangedomain.sh -> /root/BTCPayServer/btcpayserver-docker/changedomain.shRemove your BTCPay installation folder with
rm -r "$(dirname "$BTCPAY_ENV_FILE")"Just to make sure, run
docker system pruneafter a reboot to get rid of any other docker related artifacts.
Here you can find common questions and solutions to BTCPay web-deployments.
In your LunaNode dashboard, click on Virtual Machines > Your Virtual Machine > General Tab > External IP. Copy the external IP.
Go to your DNS provider and create an A record. Paste the external IP.
Go to Server Settings > Maintenance > Change Domain. Paste yourdomain.com without http or https prefix.
Additional documentation can be found on domain change page.
Check this community guide.
Your nginx config is set to route the HTTP request to a particular container based on the domain name of the request. For example, the official deployment on pi 4 was to setup the souce domain name to http://raspberrypi.local/ yet getting automatic local domain raspberrypi.local does not always work. You are probably in this situation and trying to type the IP address of your BTCPay into the web-browser.
Since nginx gets the IP address in the request instead of raspberrypi.local it does not know where to route that request and returns:
503 Service Temporarily Unavailable-----------------------------------nginx
You can fix this by forcing nginx to route the HTTP request to BTCPay even if the request domain name is not recognized. Simply, re-run the setup script like this:
sudo su -​REVERSEPROXY_DEFAULT_HOST="$BTCPAY_HOST" && . btcpay-setup.sh -i
Now putting local IP in the web-browser works.
To check, run:
sudo docker ps | less -S
Press "q" to quit out of less.
The output should contain:
btcpayserver/letsencrypt-nginx-proxy-companion
btcpayserver/btcpayserver
And the status should be "Up"
If the docker container is not running, then check the reason for crash like this:
sudo docker logs 6a6b9fd75692 --tail 20
Where 6a6b9fd75692 is the container ID that is having issues.
You might also see the following error: You access BTCPay Server over an unsecured network.
You might see this error on the front page of your BTCPay Server since version 1.0.3.73.
This is caused by a breaking change made in BTCPay to be able to handle different domain on the same server.
It happens because your BTCPay Server is not exposed directly on internet, instead a reverse proxy (like nginx or IIS) receive the request and forward it to BTCPay Server.
Sadly, depending on the configuration of your reverse proxy, either the HTTP HOST header has been replaced, or the reverse proxy did not forwarded the protocol at the front with the http header X-Forwarded-Proto.
If you use NGinx, here is what you need to have at the top level in /etc/nginx/conf.d/default.conf:
map $http_x_forwarded_proto $proxy_x_forwarded_proto {default $http_x_forwarded_proto;'' $scheme;}proxy_set_header Host $http_host;proxy_set_header X-Forwarded-Proto $proxy_x_forwarded_proto;​server_names_hash_bucket_size 128;proxy_buffer_size 128k;proxy_buffers 4 256k;proxy_busy_buffers_size 256k;client_header_buffer_size 500k;large_client_header_buffers 4 500k;http2_max_field_size 500k;http2_max_header_size 500k;
If your reverse proxy is Apache 2, you need to set those two settings
<VirtualHost *:443>RequestHeader set X-Forwarded-Proto "https"ProxyPreserveHost on...</VirtualHost>
You will also need those settings in the apache2.conf to prevent issues while signing PSBTs.
LimitRequestLine 500000LimitRequestFieldSize 500000
You need to open port 80 and 443. Once you did that, restart docker btcpay-restart.sh
There could be many causes for 5XX HTTP errors. Please create an Issue and when cause becomes known add it here in the Deployment FAQ doc.
