Troubleshooting¶
These pages help you find and fix a problem on the server. Start from the symptom: find the heading that matches what you see, then follow its Cause, Check and Fix parts in order.
Each Check uses read-only commands. They show state and change nothing. Each Fix tells you what to change. Read the cause before you apply a fix.
Pages¶
| Page | Covers |
|---|---|
| Setup | prep-airdrop.sh on the dev Mac, first-boot.sh, and run-app-setup.sh on the server |
| Plex | Plex Media Server, the NAS mount that Plex reads, the Plex watchdog, and the TVmaze sync |
| Transmission and VPN | The Podman VM, the transmission-vpn container, PIA, port forwarding, and VirtioFS access to the NAS |
| Media pipeline | The trigger watcher, FileBot, triage, pending-move/ cleanup, and Catch |
| Remote access | Caddy, TLS certificates, Cloudflare Tunnel and Access, DDNS, and the home VPN |
| Monitoring | The watchdogs, alert email, and msmtp |
Before you start¶
- Find which machine you are on. Run
hostname -sandwhoami. Most checks run on the server asadmin. - Many services run as
operator. From anadminshell, read their LaunchAgents withsudo launchctl print gui/$(id -u operator)/<label>, and run their tools withsudo -iu operator <command>. <hostname>in a label or a path is the lowercase server name.<share>isNAS_SHARE_NAMEfromconfig.conf.- Restart a launchd job with
launchctl kickstart -kp. Reload a changed plist withlaunchctl bootout, thenlaunchctl bootstrap. - Do not unmount the NAS share on the host. Plex reads from it, and the Transmission container sees it through VirtioFS.
Reference¶
- LaunchAgents and LaunchDaemons: every label, schedule and log path.
- Log files: every log that the scripts and jobs write.
- Ports: every port that the stack listens on or connects to.