BTCPay Server Cloudflare Tunnel Setup for Umbrel

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

---

Prerequisites

• BTCPay Server running on Umbrel
• Domain name (purchased from any registrar)
• Access to domain registrar account
• Access to Umbrel terminal

---

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:

• bella.ns.cloudflare.com
• carter.ns.cloudflare.com

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:

• Squarespace: Settings → Domains → [Your Domain] → DNS Settings → Nameservers
• Namecheap: Domain List → Manage → Nameservers → Custom DNS
• GoDaddy: My Products → Domains → Manage DNS → Nameservers → Change

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 [email protected]
# Default password: moneyprintergobrrr (if not changed)

Or using IP address:

ssh [email protected]
# 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:

• YOUR-TUNNEL-ID = the tunnel ID from Part 3, Step 5
• yourdomain.com = your actual domain name
• pay = your preferred subdomain (could be btcpay, payments, store, etc.)

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:

• Press Ctrl + X
• Press Y to confirm
• Press Enter

Step 4: Route DNS

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

Replace:

• btcpay-tunnel = your tunnel name (use the name from Part 3, Step 5)
• pay.yourdomain.com = your actual subdomain + domain

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:

• Use: https://pay.yourdomain.com (replace with your actual subdomain)

---

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:

• Always Use HTTPS: ON
• Automatic HTTPS Rewrites: ON

---

Part 9: Test the Connection

Step 1: Wait for DNS Propagation

Check status at: https://dnschecker.org

• Enter your subdomain (e.g., pay.yourdomain.com)
• Should show Cloudflare IPs globally (may take 30 min - 24 hours)

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

• Should show Cloudflare IP, not your home IP ✅

---

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)

• BTCPay app not running in Umbrel - restart it from Umbrel dashboard
• Wrong port in config - verify port 3007 or check docker ps
• Check Umbrel is running: visit http://umbrel.local

Tunnel shows running but site doesn’t load

• DNS not propagated yet - wait and check dnschecker.org
• Cloudflare SSL mode wrong - set to “Flexible”
• Check BTCPay allowed domains in Umbrel app settings

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

• Verify Cloudflare SSL mode is set to “Flexible”
• Check that “Always Use HTTPS” is enabled
• Clear browser cache and try again

---

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:

• Backup wallet seed phrases offline (write down, store securely - NEVER digitally)
• Change BTCPay admin password to something strong and unique
• Enable 2FA in BTCPay settings
• Verify home IP is hidden (check whatismyip.com from external network)
• Test payment flow from external network before going live
• Set up regular BTCPay database backups
• Document recovery procedures
• Review BTCPay security settings and access controls
• Keep Umbrel and BTCPay updated regularly

---

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:

• Active setup: ~1 hour
• DNS propagation wait: 15 min - 24 hours
• Total: 1-25 hours (mostly waiting)

Ongoing Costs:

• Domain: ~$10-15/year
• Cloudflare: FREE
• Electricity: ~$5-10/month (Umbrel hardware)
• Total: ~$70-135/year

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

• Cloudflare Tunnel Docs: https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/
• BTCPay Documentation: https://docs.btcpayserver.org/
• Umbrel Community: https://community.umbrel.com/
• DNS Checker: https://dnschecker.org/
• SSL Checker: https://www.sslshopper.com/ssl-checker.html

---

Installation Worksheet

Setup Information:

• Domain Name: _______________________
• Subdomain Chosen: _______________________
• Full URL: https://_______________________.com
• Tunnel Name: _______________________
• Tunnel ID: _______________________
• Cloudflare Nameserver 1: _______________________
• Cloudflare Nameserver 2: _______________________
• Setup Date: _______________________
• DNS Propagation Complete: [ ] Yes [ ] No
• Testing Complete: [ ] Yes [ ] No

---

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!

npub1q8gth72…84awvk