Troubleshooting & System Basics

Understanding your ripsline Virtual Private Node after deployment. The operating system is Ubuntu 24 LTS server.

Important Safety Note: Your BTCPay Server was installed in the /root/ directory. Commands that modify your system can be dangerous. This guide focuses on safe, read-only commands to check your system status.

Understanding Your System

Working in the Root Directory

Your BTCPay Server lives in /root/BTCPayServer/. To access it, you have two options:

Option 1: Switch to Root User

sudo su -

This switches you to the root user. You'll see your prompt change to root@hostname:~#

Option 2: Use Full Paths

You can run commands using the full path without switching to root:

/root/BTCPayServer/btcpayserver-docker/bitcoin-cli.sh getblockchaininfo

Tip: For convenience, most commands in this guide assume you've switched to root with sudo su -

Monthly VPS Maintenance

Keep your Virtual Private Server secure and up-to-date with regular maintenance. Do this at least once per month.

Step 1: Update System Packages

System updates include security patches and bug fixes. Always update regularly.

Connect to your VPS via SSH
Switch to root user:

sudo su -

Go to home directory:

cd

Update package lists and upgrade all packages:

apt update && apt upgrade -y

This will take 2-5 minutes. You'll see packages being downloaded and installed.

Step 2: Check if Reboot is Needed

After updating, check if a reboot is required (usually due to kernel updates):

ls /var/run/reboot-required

What this shows:

If you see: /var/run/reboot-required - A reboot is needed
If you see: No such file or directory - No reboot needed

Step 3: Reboot if Required

If a reboot is required (especially for kernel updates), reboot your VPS:

reboot

What happens during reboot:

Your SSH connection will disconnect (this is normal)
Wait 2-3 minutes for the VPS to restart
Your BTCPay Server will automatically start back up
All services (Bitcoin, Lightning, etc.) will resume
You can reconnect via SSH after the reboot completes

When to reboot: Always reboot if the system indicates it's required, especially after kernel updates. This ensures security patches are loaded and your system runs the latest stable kernel.

Step 4: Update BTCPay Server

After system updates, update BTCPay Server itself:

SSH back into your VPS (if you rebooted)
Switch to root:

sudo su -

Navigate to BTCPay directory:

cd ~/BTCPayServer/btcpayserver-docker

Run the BTCPay update script:

./btcpay-update.sh

This will take 5-15 minutes. Let it finish completely.

Step 5: Run Lightning Fix Script

After updating BTCPay, run the Lightning fix script to ensure your Lightning node stays reachable:

Navigate to BTCPay directory:

cd ~/BTCPayServer

Run the fix script:

./fix-lnd-host.sh

This ensures your Lightning node's public IP is correctly set after updates.

Monthly Maintenance Summary: apt update + apt upgrade → check/reboot if needed → btcpay-update.sh → fix-lnd-host.sh

Essential System Check Commands

These are safe, read-only commands you can use anytime to check your system status.

Check Bitcoin Sync Progress

See how far your Bitcoin node has synced:

cd ~/BTCPayServer/btcpayserver-docker
./bitcoin-cli.sh getblockchaininfo | grep verificationprogress

What this shows:

"verificationprogress": 0.9999 means done!
0.5 means 50% synced

Remember: Initial Bitcoin sync takes 1-5 days. This is normal!

Check Bitcoin Block Height

See what block your node is on:

cd ~/BTCPayServer/btcpayserver-docker
./bitcoin-cli.sh getblockchaininfo | grep -E "blocks|headers"

What this shows:

"blocks": 870000 - Current block height your node has synced
"headers": 870500 - Target block height (what you're syncing to)

When blocks equals headers, you're fully synced! Compare your block height to mempool.space to see current network height.

View Full Bitcoin Node Info

Get detailed information about your Bitcoin node:

cd ~/BTCPayServer/btcpayserver-docker
./bitcoin-cli.sh getblockchaininfo

What this shows:

Chain (mainnet, testnet, etc.)
Block count
Verification progress
Pruning status
And much more...

Check Disk Space

See how much disk space you have available:

Quick Check (Root Filesystem Only)

df -h | grep "/$"

What this shows:

Size - Total disk size
Used - How much is used
Avail - How much is available
Use% - Percentage used

Full Disk Usage

df -h

This shows all mounted filesystems and their usage.

Check Running Containers

See all your BTCPay Server services (Docker containers):

docker ps

What this shows:

Container names (btcpayserver_bitcoind, btcpayserver_lnd_bitcoin, etc.)
Status (Up, Restarting, Exited)
Uptime (how long they've been running)

What to look for:

All containers should show Up status
If any show Restarting repeatedly, there may be an issue
If any show Exited, that service has stopped

Lightning Node Status Commands

Check your Lightning node health and connectivity.

Full Lightning Node Info

cd ~/BTCPayServer/btcpayserver-docker
./bitcoin-lncli.sh getinfo

This shows comprehensive Lightning node information. The most important fields are explained below.

Check Lightning Sync Status

cd ~/BTCPayServer/btcpayserver-docker
./bitcoin-lncli.sh getinfo | grep -E "synced_to_chain|synced_to_graph"

What this shows:

synced_to_chain

"synced_to_chain": true - Your Lightning node is synced to the Bitcoin blockchain ✅
"synced_to_chain": false - Still syncing to blockchain ⏳

Importance: Must be true before you can open Lightning channels. If false, wait for Bitcoin to finish syncing.

synced_to_graph

"synced_to_graph": true - Your node has downloaded the Lightning Network graph ✅
"synced_to_graph": false - Still downloading network graph ⏳

Importance: Must be true before opening channels. The graph contains information about all Lightning nodes and channels. This sync usually takes 10-30 minutes after Bitcoin is synced.

Before Opening Channels: BOTH synced_to_chain AND synced_to_graph must be true!

Check Lightning Connections

cd ~/BTCPayServer/btcpayserver-docker
./bitcoin-lncli.sh getinfo | grep -E "num_peers|num_active_channels"

What this shows:

num_peers

"num_peers": 0 - Not connected to any Lightning peers
"num_peers": 3 - Connected to 3 Lightning peers

What this means:

Peers are other Lightning nodes you've connected to
You must add a peer before opening a channel with them
After adding peers in Zeus or RTL, this number will increase

num_active_channels

"num_active_channels": 0 - No active Lightning channels
"num_active_channels": 2 - You have 2 active channels

What this means:

This shows how many Lightning channels you have open and active
Starts at 0 when you first deploy
Increases as you open channels
Active means the channel is confirmed and ready to use

Additional System Status Commands

Check Nginx Status

Nginx is the web server that handles HTTPS connections to your BTCPay Server:

systemctl status nginx

What this shows:

active (running) - Nginx is working properly
inactive (dead) - Nginx is not running
failed - Nginx encountered an error

Check System Memory Usage

See how much RAM your system is using:

free -h

What this shows:

total - Total RAM available
used - RAM currently in use
free - RAM available
available - RAM available for new applications

Check System Uptime

See how long your VPS has been running:

uptime

This shows how long since the last reboot and system load averages.

Need Help?

If you run into issues:

Email: support@ripsline.com
Include your order ID
Include output from relevant commands above