BTCPay Docker users must opt into Tor at their next update to keep onion access

BTCPay Docker users must opt into Tor at their next update to keep onion access

Introduction

Operators running the Bitcoin payment software BTCPay Server through its standard Docker deployment must explicitly select Tor at their next setup or update if they want to retain onion access. The change removes Tor from the automatically included components, making a previously bundled service an administrator’s configuration choice.

Deployment Change

BTCPay detailed the deployment change in its Oct. 5 announcement accompanying version 2.4.5. The official GitHub release page records the software release on Oct. 6. For existing installations, the relevant trigger is their next Docker setup or update.

Impact on Docker Operators

The change matters to Docker operators who rely on Tor, including access through their server’s onion address, but previously received it through the core BTCPay Server fragment. Fragments are the configuration components used to assemble the Docker stack.

Enabling Tor

BTCPay advises administrators to review the deployment changes before updating. After updating to 2.4.5, its instruction for enabling Tor is: sudo btcpay-fragments add opt-add-tor Tor remains supported, and BTCPay says existing data stays in the current Tor volumes. That preserves stored data; continued onion access still depends on including and running Tor in the deployment.

Additional Changes

BTCPay Server documentation describes the optional Tor fragment opt-add-tor as adding hidden services and selected onion connectivity. Operators can inspect configuration using btcpay-fragments show, which does not change configuration and reports saved additional and excluded fragments alongside the effective fragments from the last generated manifest. Fragment-changing commands require root and reapply setup immediately.

Private Services

Private services need separate exceptions The 2.4.5 release notes also identify a breaking change for outbound HTTP requests: private-network destinations are blocked by default for Lightning connections, LNURL requests, invoice notification URLs and webhooks. The restriction is intended to prevent server-side request forgery, or SSRF. With that protection enabled, operators intentionally using private services must allow the needed destinations through ssrfexceptions.

Conclusion

BTCPay’s operator guide says to restart the application and exercise the affected integration after changing the setting.