BTCPay Server Cloudflare Tunnel Setup for Umbrel

Complete guide to expose BTCPay Server running on Umbrel to the internet via Cloudflare Tunnel while keeping your home IP private.

The Bullish ₿itcoiner

17. Oktober 2025October 17, 2025 · 9 Min. Lesezeit9 min read · Aktualisiert am 30. Oktober 2025Updated October 30, 2025

Setup Time: ~1 hour + DNS propagation (15 min - 24 hours)

Prerequisites#

Part 1: Domain Setup with Cloudflare (21 minutes)#

Step 1: Create Cloudflare Account#

  1. Go to https://www.cloudflare.com/
  2. Click “Sign Up” (free account)
  3. Verify email

Step 2: Add Domain to Cloudflare#

  1. Click “Add a Site” in Cloudflare dashboard
  2. Enter your domain name (e.g., yourdomain.com)
  3. Select “Free” plan
  4. Click “Continue”

Step 3: Update Nameservers at Your Domain Registrar#

Cloudflare will show you two nameservers like:

At Your Domain Registrar (Squarespace, Namecheap, GoDaddy, etc.):

  1. Log into your domain registrar account
  2. Find domain management/DNS settings
  3. Look for “Nameservers” section
  4. Change from default nameservers to “Custom Nameservers”
  5. Enter the two Cloudflare nameservers provided
  6. Save changes

Common Registrars:

Note: DNS propagation takes 1-24 hours (usually 15-60 minutes)

Part 2: Access Umbrel Terminal#

Choose one method:

Option A: From Umbrel Dashboard (Easier)#

  1. Open Umbrel dashboard (http://umbrel.local or http://192.168.x.x)
  2. Click the three dots menu (top right)
  3. Click “Terminal” or “Advanced”
  4. This opens a web-based terminal

Option B: SSH from Another Computer#

ssh umbrel@umbrel.local
# Default password: moneyprintergobrrr (if not changed)

Or using IP address:

ssh umbrel@192.168.x.x
# Replace x.x with your actual IP address

Part 3: Install Cloudflare Tunnel on Umbrel (15 minutes)#

Once in the terminal:

Step 1: Download Cloudflared#

For Umbrel Home (x86/AMD64):

cd ~
curl -L --output cloudflared https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64

For Umbrel on Raspberry Pi (ARM):

cd ~
curl -L --output cloudflared https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm64

Step 2: Make it Executable#

chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/

Step 3: Verify Installation#

cloudflared --version

Should show version number.

Step 4: Authenticate with Cloudflare#

cloudflared tunnel login

This will output a URL like:

Please open the following URL in your browser:
https://dash.cloudflare.com/argotunnel?callback=https://...

Copy that entire URL and paste it into a browser. Then:

  1. Log into Cloudflare
  2. Select your domain from the list
  3. Click “Authorize”

You’ll see: “You have successfully logged in”

Step 5: Create the Tunnel#

cloudflared tunnel create btcpay-tunnel

You’ll see output like:

Created tunnel btcpay-tunnel with id: abc123def-456g-789h-ijk012lmn

IMPORTANT: Copy and save that tunnel ID somewhere safe! You’ll need it in the next steps.

Part 4: Find BTCPay Port on Umbrel#

BTCPay on Umbrel typically runs through Umbrel’s proxy on port 3007.

To verify:

# Check Umbrel's proxy port
curl -I http://localhost:3007

# Or check BTCPay container directly
docker ps | grep btcpay

For Umbrel, we’ll use port 3007 which routes to all Umbrel apps.

Part 5: Configure the Tunnel (10 minutes)#

Step 1: Create Config Directory#

mkdir -p ~/.cloudflared

Step 2: Create Configuration File#

nano ~/.cloudflared/config.yml

Step 3: Add Configuration#

Replace the following placeholders:

tunnel: YOUR-TUNNEL-ID
credentials-file: /home/umbrel/.cloudflared/YOUR-TUNNEL-ID.json

ingress:
  - hostname: pay.yourdomain.com
    service: http://localhost:3007
    originRequest:
      noTLSVerify: true
  - service: http_status:404

Example filled in:

tunnel: abc123def-456g-789h-ijk012lmn
credentials-file: /home/umbrel/.cloudflared/abc123def-456g-789h-ijk012lmn.json

ingress:
  - hostname: pay.example.com
    service: http://localhost:3007
    originRequest:
      noTLSVerify: true
  - service: http_status:404

Save the file:

Step 4: Route DNS#

cloudflared tunnel route dns btcpay-tunnel pay.yourdomain.com

Replace:

This creates a DNS record in Cloudflare pointing your subdomain to the tunnel.

Part 6: Create Systemd Service (Run Tunnel Automatically)#

Step 1: Create Service File#

sudo nano /etc/systemd/system/cloudflared.service

Step 2: Paste This Configuration#

[Unit]
Description=Cloudflare Tunnel
After=network.target

[Service]
Type=simple
User=umbrel
ExecStart=/usr/local/bin/cloudflared tunnel --config /home/umbrel/.cloudflared/config.yml run
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Save with Ctrl + X, Y, Enter

Step 3: Enable and Start Service#

# Reload systemd to recognize new service
sudo systemctl daemon-reload

# Enable auto-start on boot
sudo systemctl enable cloudflared

# Start the service now
sudo systemctl start cloudflared

# Check status
sudo systemctl status cloudflared

Should show “active (running)” in green.

Part 7: Configure Umbrel BTCPay App#

  1. Open Umbrel dashboard
  2. Go to BTCPay app
  3. Click settings (three dots or gear icon)
  4. Look for domain/URL settings
  5. Add your subdomain (e.g., pay.yourdomain.com) as an allowed domain if prompted

If BTCPay asks for a domain during initial setup:

Part 8: Configure Cloudflare SSL Settings#

  1. Go to Cloudflare dashboard
  2. Select your domain
  3. Go to SSL/TLS section
  4. Set SSL/TLS encryption mode to “Flexible” (Umbrel uses self-signed certs internally)
  5. Go to SSL/TLS → Edge Certificates
  6. Enable:

Part 9: Test the Connection#

Step 1: Wait for DNS Propagation#

Check status at: https://dnschecker.org

Step 2: Test from Outside Network#

  1. Disable WiFi on your phone (use cellular data)
  2. Visit: https://pay.yourdomain.com (replace with your actual URL)
  3. You should see BTCPay interface

Step 3: Verify IP is Hidden#

Visit: https://www.whatismyip.com

Troubleshooting#

“This site can’t be reached”#

# Check tunnel status
sudo systemctl status cloudflared

# View logs
sudo journalctl -u cloudflared -f

# Restart tunnel
sudo systemctl restart cloudflared

“Bad Gateway” (502)#

Tunnel shows running but site doesn’t load#

Can access BTCPay through Umbrel but not through domain#

Check BTCPay container logs:

docker logs $(docker ps | grep btcpay | awk '{print $1}')

Access BTCPay through Umbrel interface and verify domain settings.

Certificate/SSL errors#

Helpful Commands for Future Reference#

# Check tunnel status
sudo systemctl status cloudflared

# Restart tunnel
sudo systemctl restart cloudflared

# Stop tunnel
sudo systemctl stop cloudflared

# View live logs
sudo journalctl -u cloudflared -f

# View recent logs
sudo journalctl -u cloudflared -n 50

# Check what's running on Umbrel
docker ps

# View tunnel list
cloudflared tunnel list

# Delete a tunnel (if needed)
cloudflared tunnel delete TUNNEL-NAME

Security Checklist (CRITICAL)#

Before making BTCPay internet-accessible:

What You Get#

✅ BTCPay accessible via your custom domain
✅ Home IP completely hidden
✅ Free Cloudflare DDoS protection
✅ Professional setup for business use
✅ No router port forwarding needed
✅ Works behind CGNAT/restrictive ISPs
✅ Automatic SSL/HTTPS encryption

Summary#

Time Investment:

Ongoing Costs:

What You Need:

  1. Access to domain registrar account
  2. Cloudflare account (free)
  3. Access to Umbrel terminal
  4. Patience for DNS propagation

Support Resources#

Installation Worksheet#

Setup Information:

Notes#

Only thing I would mention is that the newest versions of Umbrel will overwrite any custom changes when upgrading. Something to keep in mind, the tunnel may need to be fixed after any Umbrel OS upgrades.

There is also a cloudflare app in the Umbrel App Store that will achieve a similar result btw, but the method described in the guide is the right way!

⁠Filou

#btcpayserver#longform#umbrel

Written by

The Bullish ₿itcoiner

Building: @npub129v9dmq755fmy4xfs75k7uw0ydsp92uc2c9nl2k5ff65er84af5qlht6js @npub150fuklz67kkmu4t9pxq640u53sv0nycvf0dq9grmtmqhdkcxdy0sdfpc20 @npub1satse5grv0wq5tzndskkrn09g0tph0tx9kek8lycv8j3vvtva8jqzyp976…

Comments

No comments yet. Start the conversation.

Contents

18 sections

  1. Prerequisites
  2. Part 1: Domain Setup with Cloudflare (21 minutes)
  3. Part 2: Access Umbrel Terminal
  4. Part 3: Install Cloudflare Tunnel on Umbrel (15 minutes)
  5. Part 4: Find BTCPay Port on Umbrel
  6. Part 5: Configure the Tunnel (10 minutes)
  7. Part 6: Create Systemd Service (Run Tunnel Automatically)
  8. Part 7: Configure Umbrel BTCPay App
  9. Part 8: Configure Cloudflare SSL Settings
  10. Part 9: Test the Connection
  11. Troubleshooting
  12. Helpful Commands for Future Reference
  13. Security Checklist (CRITICAL)
  14. What You Get
  15. Summary
  16. Support Resources
  17. Installation Worksheet
  18. Notes