Skip to content

Operations & Troubleshooting

This page is the practical command playbook for running, validating, and troubleshooting the private cloud stack.

✅ Core Project Commands

1) Access and system identity

ssh pi@picloud.local
hostnamectl
uname -a

2) Storage and boot validation

lsblk
df -h
sudo blkid

If SSD migration must be repeated:

sudo rpi-clone sda

3) Nextcloud (Snap) deployment and status

sudo apt install snapd -y
sudo snap install nextcloud
sudo snap list | grep nextcloud
sudo snap services nextcloud

4) Nextcloud trusted domains (local + Tailscale)

sudo nextcloud.occ config:system:get trusted_domains
sudo nextcloud.occ config:system:set trusted_domains 1 --value="<YOUR-TAILSCALE-IP>"
sudo nextcloud.occ config:system:set trusted_domains 2 --value="<YOUR-MAGICDNS-HOSTNAME>"

5) Network checks

ip addr
ip route
ping -c 4 1.1.1.1
ping -c 4 google.com

(ifconfig can be used if installed, but ip addr is preferred on modern Debian/Raspberry Pi OS.)

6) Tailscale installation and connectivity

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
tailscale status
tailscale ip -4
tailscale ip -6

7) Service logs and diagnostics

sudo journalctl -xeu snap.nextcloud.apache.service --no-pager
sudo journalctl -xeu snap.nextcloud.mysql.service --no-pager
sudo journalctl -xeu snap.nextcloud.php-fpm.service --no-pager
sudo journalctl -u tailscaled --no-pager --since "30 min ago"

8) Package and system updates

sudo apt update && sudo apt upgrade -y
sudo snap refresh
sudo reboot

🧯 Common Problems and Fixes

Problem: Access through untrusted domain

Cause: Current URL/IP is not listed in trusted domains.
Fix:

sudo nextcloud.occ config:system:get trusted_domains
sudo nextcloud.occ config:system:set trusted_domains <INDEX> --value="<DOMAIN-OR-IP>"

Problem: Tailscale connected, but Nextcloud fails on phone

Checks:

tailscale status
tailscale ip -4
sudo snap services nextcloud

Tips: - Confirm phone is logged into the same Tailscale account/tailnet. - Test with both MagicDNS hostname and Tailscale IP. - Ensure mobile network allows outbound VPN traffic.

Problem: Cannot reach Pi over SSH

Checks:

ping -c 4 picloud.local
ip addr
sudo systemctl status ssh --no-pager

Fix:

sudo systemctl restart ssh

Problem: Low disk space

Checks:

df -h
sudo du -sh /var/snap/nextcloud/common/*

Tips: - Clean unused files in Nextcloud data directories carefully. - Move large temporary files off the root filesystem. - Keep user content on SSD-backed storage.

Problem: Snap services not healthy

Checks:

sudo snap services nextcloud
sudo journalctl -xeu snap.nextcloud.apache.service --no-pager

Fix:

sudo snap restart nextcloud

🧠 Professional Troubleshooting Tips

  • Change one variable at a time and retest after each change.
  • Capture evidence first (status, logs, IP, routes) before restarting services.
  • Use known-good checkpoints from this documentation to isolate the failing stage.
  • Redact sensitive data (IP addresses, DNS hostnames, account identifiers) before sharing screenshots.
  • Document final fix immediately so recurring issues can be resolved faster next time.