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.
For example if you plug a USB drive, and find out that it is the volume /dev/sda1, then:
# Format the drivesudo mkfs.ext4 /dev/sda1# Create folder for mount.sudo mkdir /mnt/usb# Look up UUID of flash drive.UUID="$(sudo blkid -s UUID -o value /dev/sda1)"# Add mount to fstab.echo "UUID=$UUID /mnt/usb ext4 defaults,nofail 0" | sudo tee -a /etc/fstab# Mount the new drivemount /dev/sda1# Define `/var/lib/docker` as symbolic link to /mnt/usbsudo mkdir /mnt/usb/dockersudo ln -s /mnt/usb/docker /var/lib/docker
If you want to mount specific folder (like only Bitcoin node data directory), please browse /var/lib/docker/volumes to chose the different docker volumes.
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 trafic 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.
It is theoretically possible, but not recommended. Reasons being that it's not documented, making it difficult and time consuming. You would need to understand what docker-compose is doing, watch this video. If you are not technically able, it's much easier to use the nodes included in the BTCPay deployment.
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.
You need to open port 80 and 443. Once you did that, restart docker btcpay-restart.sh
Check this community guide.
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
