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/

1. Click “Sign Up” (free account)

1. Verify email

### Step 2: Add Domain to Cloudflare

1. Click “Add a Site” in Cloudflare dashboard

1. Enter your domain name (e.g., yourdomain.com)

1. Select “Free” plan

1. 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

1. Find domain management/DNS settings

1. Look for “Nameservers” section

1. Change from default nameservers to “Custom Nameservers”

1. Enter the two Cloudflare nameservers provided

1. 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)

1. Click the three dots menu (top right)

1. Click “Terminal” or “Advanced”

1. This opens a web-based terminal

### Option B: SSH from Another Computer

```bash

ssh umbrel@umbrel.local

# Default password: moneyprintergobrrr (if not changed)

```

Or using IP address:

```bash

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):

```bash

cd ~

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

```

For Umbrel on Raspberry Pi (ARM):

```bash

cd ~

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

```

### Step 2: Make it Executable

```bash

chmod +x cloudflared

sudo mv cloudflared /usr/local/bin/

```

### Step 3: Verify Installation

```bash

cloudflared --version

```

Should show version number.

### Step 4: Authenticate with Cloudflare

```bash

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

1. Select your domain from the list

1. Click “Authorize”

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

### Step 5: Create the Tunnel

```bash

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:

```bash

# 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

```bash

mkdir -p ~/.cloudflared

```

### Step 2: Create Configuration File

```bash

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.)

```yaml

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:

```yaml

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

```bash

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

```bash

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

```

### Step 2: Paste This Configuration

```ini

[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

```bash

# 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

1. Go to BTCPay app

1. Click settings (three dots or gear icon)

1. Look for domain/URL settings

1. 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

1. Select your domain

1. Go to SSL/TLS section

1. Set SSL/TLS encryption mode to “Flexible” (Umbrel uses self-signed certs internally)

1. Go to SSL/TLS → Edge Certificates

1. 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)

1. Visit: https://pay.yourdomain.com (replace with your actual URL)

1. 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”

```bash

# 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:

```bash

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

```bash

# 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

1. Cloudflare account (free)

1. Access to Umbrel terminal

1. 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!

>

>@Filou