BTCPay Server

# Local development

# Prerequisites

For the development environment you need to install these tools:

# Dependencies

To execute tests and run the project for debugging, you need to run a number of dependencies.

We wrapped all our dependencies in a docker-compose file that you can use to bootstrap the development environment: The file BTCPayServer.Tests/docker-compose.yml (opens new window) can be used to spin everything up:

git clone https://github.com/btcpayserver/btcpayserver.git
cd btcpayserver/BTCPayServer.Tests
docker-compose up dev

# Which IDE?

We recommend using Visual Studio 2022 (Windows Only) or Rider (cross platform). Visual Studio Code (cross platform) should also be possible, but isn't as straightforward to setup for a comfortable development environment. You can of course use VIM if you are hardcore, .NET Core is easy to use via command-line.

Visual Studio Code, Visual Studio and Rider will run the launch profile Bitcoin. This will run a BTCPay Server instance connecting to the services in your Docker service, so you can easily debug and step through the code.

# Build configuration

A build configuration defines how to build BTCPay Server. For example, whether to include some source files, whether to optimize for debugging or performance.

There are several build configurations:

  • Debug
  • Release
  • Altcoins-Debug
  • Altcoins-Release

How to use a different one during your local development depends on your IDE. By default Debug is used, this is a Bitcoin only build excluding any altcoin dependencies. How to use a different one during your local development depends on your IDE.

You can select which build to use via the -c switch in dotnet command line. If you use command line and want to run a Release build:

dotnet run -c Release

# Launch profiles

When you start BTCPay Server locally for local development, it needs the right parameter so it can connect to the development time dependencies in the docker-compose file.

Those parameters are wrapped into the dotnet concept of launch profile.

The launch profiles are specified in the launchSettings.json (opens new window).

There are currently three launch profiles:

  • Bitcoin
  • Bitcoin-HTTPS
  • Altcoins-HTTPS

By default, Bitcoin is used. How to use a different one during your local development depends on your IDE.

If you use command line, dotnet run allows you to select the launch profile of your choice:

dotnet run --launch-profile Bitcoin

# Running tests

Running tests is functioning in the exact same way as running the development time BTCPay Server.

cd BTCPayServer.Tests
dotnet test

The concept of launch profile does not apply for tests, but the concept of build configuration does. For example, if I want to run tests on the Release build:

dotnet test -c Release

The tests are already configured to use the development time dependencies in the docker-compose presented earlier.

You can use the --f (filter) switch to run a specific test.

If you use an IDE, consult your IDE documentation to run tests or switch to different configurations.

# Altcoin support development

By default, your IDE or simple dotnet run will use Bitcoin launch profile on Debug build.

If you want to develop with altcoins support you need to use the Altcoins-HTTPS launch profile, on the Altcoins-Debug build, and run the BTCPayServer.Tests/docker-compose.altcoins.yml (opens new window).

If using command line:

cd BTCPayServer.Tests
docker-compose -f docker-compose.altcoins.yml up dev
cd ../BTCPayServer
dotnet run -c Altcoins-Debug --launch-profile Altcoins-HTTPS

For tests

cd BTCPayServer.Tests
dotnet test -c Altcoins-Debug

# HTTPS support for local development

Some browser security features may require that you use HTTPS to be properly tested.

In this case, use Bitcoin-HTTPS (or Altcoin-HTTPS) launch profile. This will create a self signed certificate for your development purpose.

However, your browser will not trust it, making it difficult to debug.

You can instruct your OS to trust this development time certificate by running:

dotnet dev-certs https --trust

# Videos

For more information check out these videos:

and these notes: