BTCPay Server Interface

BTCPay Server - Server settings

Mastering BTC Pay Server

BTCPay Server - Server settings

Users
Server-wide custom Roles
Server-wide custom Roles
Email
Policies
Services
Theme
Maintenance
Logs
Files
Skill Summary
Knowledge assessment

BTCPay Server consists of two different settings views. One is dedicated to Store settings, and the other to Server settings. The latter is only available to server administrators and not to store owners. Server administrators can add users, create custom roles, configure the email server, set policies, run maintenance tasks, check all services attached to BTCPay Server, upload files to the server, or check Logs.

Users

As mentioned in the previous part, Server Administrators can invite users to their server by adding them to the Users tab.

Server-wide custom Roles

BTCPay Server has two types of custom roles: store-specific custom roles and server-wide Custom roles in the BTCPay Server settings. Both hold a similar set of permissions; however, if set through the BTCpay Server Settings - Roles tab, the applied role will be server-wide and apply to multiple stores. Notice a "Server-wide" tag to the custom roles in Server settings.

Server-wide custom Roles

Server-wide custom roles permission set;

Modify your stores.
Manage exchange accounts linked to your stores.
- View exchange accounts linked to your stores.
Manage your pull payments.
Create pull payments.
- Create non-approved pull payments.
Modify invoices.
- View invoices.
- Create an invoice.
- Create invoices from the lightning nodes associated with your stores.
View your stores.
- View invoices.
- View your payment requests.
- Modify stores’ webhooks.
Modify your payment requests.
- View your payment requests.
Use the lightning nodes associated with your stores.
- View the lightning invoices associated with your stores.
- Create invoices from the lightning nodes associated with your stores.
Deposit funds to exchange accounts linked to your stores.
Withdraw funds from exchange accounts to your store.
Trade funds on your store’s exchange accounts.

!?Note!?

When the role gets created, the name is fixed and cannot be changed after it is in edit mode.

Email

The Server-wide Email settings look similar to those in the Store-specific email settings. However, this setup handles not only triggers for stores or administrator logs, but also triggers for other events. This Email setup also makes password recovery available on BTCPay Server at Login. It works similarly to the Store-specific settings; administrators can quickly fill in their Email parameters and enter their email credentials, allowing the server to send emails.

Policies

BTCPay Server policy administrators can set various settings on topics such as Existing User settings, New User settings, Notification settings, and Maintenance settings. These are intended for registering new users as administrators or regular users, or for hiding the BTCPay Server from search engines by adding it to your server header.

Existing user Settings

The options available here are separate from custom roles. These additional permissions may make a store or its owner vulnerable to attacks. Policies that may be added to existing users:

Allow non-admins to use the internal Lightning node in their stores.
- This would allow store owners to use the server Administrator’s Lightning node and, therefore, his funds! Beware, this is not a solution to giving access to Lightning.
Allow non-admins to create hot wallets for their stores.
- This would allow anyone with an account on your BTCPay Server instance to create Hot-wallets and store their recovery seed on the Administrator’s server. This might make the Administrator liable for holding third-party funds!
Allow non-admins to import hot wallets for their stores.
- Similar to the previous topic of creating Hot wallets, this policy allows importing a hot wallet, with the same dangers mentioned in the creating hot wallets section.

New user settings

We can set some important settings to manage new users coming to the server. We can set a confirmation email for new registrations, Disable new user creation through the login screen, and restrict non-admins' access to user creation over the API.

Require a confirmation email for registration.
- The server administrator must have set up an Email server.
Disable new user registration on the server
Disable non-admins' access to the user creation API endpoint.

By default, BTCPay Server has toggled "Disable new user registration on the server" and turned off non-admins' access to the user creation API endpoint. This is for security, so random people who stumble across your BTCPay login can’t create accounts.

Notification Settings

Maintenance Settings

BTCPay Server is an Open Source project that lives on GitHub. Whenever BTCPay Server releases a new version of the software, Administrators can be notified that a new version is available. Administrators may also want to avoid search engines (such as Google, Yahoo, and DuckDuckGo) from indexing the BTCPay Server domain. As BTCPay Server is FOSS, developers worldwide may want to create new features. BTCPay Server has an experimental feature that, when toggled on, allows administrators to use features not intended for production, but rather for testing purposes.

Check releases on GitHub and notify when a new BTCPay Server version is available.
Discourage search engines from indexing this site
Enable experimental features.

Plugins

BTCPay Server can add Plugins and expand its feature set. The plugins, by default, are loaded from the BTCPay Server plugin-builder repository. An administrator, however, may choose to see plugins in a Pre-release state, and if the plugin developer allows it, the server administrator can now install beta versions of plugins.

Customization Settings

A standard BTCPay Server deployment will be accessible through the domain set up during installation. However, a server administrator can remap the root domain and display one of the created apps from a specific store. The Server Administrator can also map specific domains to specific apps.

Display the app on the website’s root
- Displays a list of possible apps to show on the root domain.

Map specific domains to specific apps.
- When you click to set up a specific domain for specific apps, the Administrator can set as many domains pointed to specific apps as needed.

Block explorers

BTCPay Server, as standard, comes with mempool.space as its Block explorer for transactions. When BTCPay Server generates a new invoice and a transaction is tied to it, the store owner can click to open the transaction. BTCPay Server will, by default, point towards mempool.space as a block explorer; however, a server Administrator may change this to their preferred option.

Services

The "BTCPay Server settings: Services" tab is an overview of the components your BTCPay Server uses. The services your BTCPay Server exposes might vary depending on the deployment method.

A BTCPay Server Administrator can click on the “See information “behind each service to open it and set specific settings.

LND (gRPC)

BTCPay exposes LND’s GRPC service for outside consumption; you will find connection information in this specific settings menu; compatible wallets are listed here. BTCPay Server also provides a QR code for connection, which can be scanned and applied in a mobile wallet.

Server administrators can open more details to see.

Host details
Use of SSL
Macaroon
AdminMacaroon
InvoiceMacaroon
ReadonlyMacaroon
GRPC SSL Cipher suite (GRPC_SSL_CIPHER_SUITES)

LND (REST)

BTCPay exposes LND’s REST service for outside consumption; you will find connection information here; compatible wallets are listed here. Among the compatible wallets are Joule, Alby, and ZeusLN. BTCPay Server provides a QR code for connection, which can be scanned and applied in a compatible wallet.

REST URI
Macaroon
AdminMacaroon
InvoiceMacaroon
ReadonlyMacaroon

LND Seed Backup

The LND seed backup is useful for recovering funds from your LND wallet in case of server corruption. As the Lightning node is a Hot-wallet, you can find the confidential seed information on this page.

LND documents the recovery process. See https://github.com/lightningnetwork/lnd/blob/master/docs/recovery.md for documentation.

Ride The Lightning

Ride the Lightning is a Lightning node management tool built as Open Source software. BTCPay Server uses RTL as the Lightning node management component in its stack. BTCPay Server administrators can reach RTL through the Server settings - Services tab or by clicking on the Lightning wallet.

Full node P2P

Server administrators may want to connect their Bitcoin node to a mobile wallet. This page provides information on how to connect remotely to your full node via the P2P protocol. As of the writing of this course, BTCPay Server lists Blockstream Green and Wasabi wallets as compatible wallets. BTCPay Server provides a QR code for connection, which can be scanned and applied in a compatible wallet.

Full node RPC

This page exposes information to connect remotely to your full node via the RPC protocol.

SSH

SSH is used for maintenance purposes. BTCPay Server shows the initial connection command to reach your Server and SSH public keys authorized to connect to your Server. Server administrators may want to disable SSH changes through the BTCPay Server UI.

Dynamic DNS

Dynamic DNS allows you to have a stable DNS name pointing to your Server, even if your IP address changes regularly. This is recommended if you are hosting BTCPay Server at home and wish to have a clearnet domain to access your Server.

Note that you need to properly configure your NAT and BTCPay Server installation to get the HTTPS certificate.

Theme

BTCPay Server, as standard, comes with two themes: Light and Dark modes. These can be switched by clicking on Account in the bottom left and toggling between Dark theme and Light theme. BTCPay Server administrators can add their own theme by providing a custom CSS theme.

Administrators can extend the Light/Dark theme by adding their own custom CSS or setting their custom theme as a full custom.

Server Branding

Server administrators can change the BTCPay Server branding by setting a Server-wide branding of your company. As BTCPay Server is FOSS, server administrators can white-label the software and customize the look to suit their business.

Maintenance

As a server administrator, your users expect you to take good care of the Server. Within BTCPay Server’s Maintenance tab, the admin can do some essential maintenance. Set the domain name to the BTCPay Server instance, Restart or clean up the Server. Possibly most important, run updates.

BTCPay Server is an Open Source project and updates frequently. Every new release is announced by either your BTCPay Server Notifications or on the official Channels BTCPay Server communicates through.

Domain name

After BTCPay Server is set up, an administrator might want to change away from their original Domain. Within the Maintenance tab, the administrator can change the Domain. After clicking confirm and setting up the proper DNS records on the Domain, BTCPay Server updates and restarts to return to the new Domain.

Restart

Restart BTCPay Server and related services.

Clean

BTCPay Server runs with Docker components; with updates, there might be leftovers of Docker images, temp files, etc. Server administrators can free up space by running the Clean script.

Update

It's the most important option in the Maintenance tab. BTCPay Server is built by the community, and therefore, its update cycles are more frequent than most software products. When BTCPay Server has a new release, administrators will be notified in their notification center. By clicking the update button, BTCPay Server will check GitHub for the latest release, update the Server and restart. Before updating, server administrators are always advised to read the release notes distributed through the official channels of BTCPay Server.

Logs

Facing a problem is never fun. This document outlines the most common workflow and steps to efficiently identify and resolve your issue, either independently or with community assistance.

Identifying the problem is crucial.

Replicating the issue

First and foremost, try to determine when the issue happens. Try to replicate the problem. Try updating and restarting your Server to verify that you can reproduce the issue. If it better describes your issue, take a screenshot.

Updating the server

Check your version of BTCPay Server if it is much older than the latest version of BTCPay Server. Updating your Server may resolve the issue.

Restarting the server

Restarting your Server is an easy way to solve many of the most common BTCPay Server issues. You may need to SSH into your Server so you can restart it.

Restarting a service

You may only need to restart a particular service in your BTCPay Server deployment for some issues, such as restarting the letsencrypt container to renew the SSL certificate.

sudo su -
cd btcpayserver-docker
docker restart letsencrypt-nginx-proxy-companion

Use docker ps to find the name of a different service you would like to restart.

Looking through the logs

Logs can provide an essential piece of information. In the following paragraphs, we will describe how to get the log information for various parts of BTCPay.

BTCPay Logs

Since v1.0.3.8, you can easily access BTCPay Server logs from the front end. If you are a server admin, go to Server Settings > Logs and open the logs file. If you do not know what a particular error in the logs means, mention it when troubleshooting.

If you want more detailed logs and are using a Docker deployment, you can view logs of specific Docker containers using the command line. See these instructions to ssh into an instance of BTCPay running on a VPS.

On the next page, a general list of the container names used for BTCPay Server.

Run the commands below to print logs by container name. Replace the container name to view other container logs.

sudo su -
cd btcpayserver-docker
docker ps
docker logs --tail 100 generated_btcpayserver_1

Logs for	Container Name
BTCPayServer	generated_btcpayserver_1
NBXplorer	generated_nbxplorer_1
Bitcoind	btcpayserver_bitcoind
Postgres	generated_postgres_1
proxy	letsencrypt-nginx-proxy-companion
Nginx	nginx-gen
Nginx	nginx
c-lightning	btcpayserver_clightning_bitcoin
LND	btcpayserver_lnd_bitcoin
RTL	generated_lnd_bitcoin_rtl_1
Thunderhub	generated_bitcoin_thub_1
LibrePatron	librepatron
Tor	tor-gen
Tor	tor

Lightning Network LND - Docker

There are a few ways to access your LND logs when using Docker. First, log in as root:

sudo su -
Navigate to the correct directory:
cd btcpayserver-docker
# Find container name:
docker ps
Print logs by container name:
docker logs --tail 100 btcpayserver_lnd_bitcoin

Alternatively, you can quickly print logs by using the container ID (only the first unique ID characters are needed, such as the two furthest left characters):

docker logs 'add your container ID'

If, for any reason, you need more logs

sudo su -
cd /var/lib/docker/volumes/generated_lnd_bitcoin_datadir/\_data/logs/ bitcoin/mainnet/
ls

You will see something like

lnd.log lnd.log.13 lnd.log.15 lnd.log.16.gz lnd.log.17.gz

To access uncompressed logs of those logs, do cat lnd.log or if you want another one, use cat lnd.log.15.

To access compressed logs in .gzip, use gzip -d lnd.log.16.gz (in this case, we're accessing lnd.log.16.gz). This should give you a new file, where you can do cat lnd.log.16. In case the above does not work, you may need to install gzip first with sudo apt-get install gzip.

Lightning Network c-lightning - Docker

sudo su -
docker ps
# Find the c-lightning container ID.
docker logs 'add your container ID here'

Alternatively, use this:

docker logs --tail 100 btcpayserver_clightning_bitcoin

You can also get log information with c-lightning cli command.

bitcoin-lightning-cli.sh getlog

Bitcoin Node Logs

In addition to looking at logs of your Bitcoind container, you can also use any of the bitcoin-cli commands

Open a new window to obtain information from your bitcoin node. BTCPay includes a script to allow you to communicate with your Bitcoin node easily.

Inside the btcpayserver-docker folder, get the blockchain information using your node:

bitcoin-cli.sh getblockchaininfo

Files

BTCPay Server features a local file system, allowing it to upload store (product) assets, Logos, and branding directly to the Server. The server’s file system is only accessible by Server Administrators; store owners can upload their logos or branding at the store level.

When the Server administrator is in the File Storage tab, it is possible to directly upload to your Server or change the file storage provider to a Local file system or Azure Blob Storage.

Skill Summary

In this section, you learned the following:

The difference between Store and Server settings, in particular as they relate to Users, Roles, and Emails
Set server-wide policies for Lightning or Bitcoin hot wallet use and creation, new user registration, and email notifications.
How to add custom themes (instead of simple light/dark options provided) as well as create custom logos
Perform simple server maintenance tasks via the GUI provided
Troubleshoot issues, including fetching details for any of the Docker containers or your node
Manage file storage

Knowledge assessment

KA Conceptual Review

What is the difference in Roles assigned through Server vs Store Settings, and what describes a potential use for one over the other?

KA Practical Review

Describe some possible use cases enabled in the Policies tab.

KA Practical Review

Describe some actions an administrator might routinely make in the Maintenance tab.