Scripts¶
This page lists every script in the repo's root, app-setup/, app-setup/templates/, and scripts/, derived from each file's header comment, its root check, and the setup script that deploys it.
"Runs as" is the account the script expects. "admin" means the admin account, with sudo prompts where a step needs root. "root" means that you start it with sudo or that launchd starts it as root. Links go to the file on GitHub.
Repository root¶
| Path | Runs on | Runs as | Purpose |
|---|---|---|---|
prep-airdrop.sh |
Dev Mac | Your user | Builds the setup package: gets credentials from 1Password, writes the hardware fingerprint, Wi-Fi strategy and manifest, and copies the scripts to ~/<hostname>-setup |
run_tests.sh |
Dev Mac | Your user | Runs the BATS unit and integration tests |
prep-airdrop.sh [output_path] [script_path] takes two optional arguments. output_path is the package folder, ~/<server name>-setup by default, with the server name lowercased. script_path is the folder that holds the scripts to copy, the current folder by default.
scripts/airdrop¶
| Path | Runs on | Runs as | Purpose |
|---|---|---|---|
scripts/airdrop/rclone-airdrop-prep.sh |
Dev Mac | Your user | Installs rclone, runs the Dropbox OAuth sign-in, and adds the rclone config to the setup package. prep-airdrop.sh calls it. |
scripts/docs¶
| Path | Runs on | Runs as | Purpose |
|---|---|---|---|
scripts/docs/gen-config-reference.sh |
Dev Mac or CI | Your user | Writes config keys from config/config.conf.template. --check exits 1 if the page is stale. |
scripts/server¶
These scripts are copied into the setup package. first-boot.sh calls the setup-*.sh modules in order. You can run a module again by itself.
first-boot.sh options:
--forceskips the confirmation prompts. Do not use it on a first run; see Run first boot.--skip-homebrewskips the Homebrew install and configuration.--skip-packagesskips the formulae and casks inconfig/formulae.txtandconfig/casks.txt.--skip-updateis accepted but changes nothing. The script always skips macOS software updates, because they are unreliable during setup.
| Path | Runs on | Runs as | Purpose |
|---|---|---|---|
first-boot.sh |
Server | admin | System provisioning: fingerprint check, FileVault check, then each setup module |
setup-apple-id.sh |
Server | admin | Apple Account sign-in and iCloud settings |
setup-application-preparation.sh |
Server | admin | Copies the app-setup folder and operator files into place, and installs the operator first-login LaunchAgent |
setup-auto-updates.sh |
Server | admin (refuses root) | Daily Homebrew upgrade daemon, stable signing, App Store auto-update, and the weekly download-only macOS update daemon |
setup-bash-configuration.sh |
Server | admin | Bash configuration for the admin and operator accounts |
setup-command-line-tools.sh |
Server | admin | Installs the Xcode Command Line Tools and reports progress |
setup-dock-configuration.sh |
Server | admin | Removes default Dock apps and adds utilities, with dockutil |
setup-firewall.sh |
Server | admin | Turns on the application firewall and allows SSH |
setup-hostname-volume.sh |
Server | admin | Sets the computer name and local host name, and renames the system volume to match |
setup-log-rotation.sh |
Server | admin | Installs logrotate.conf and starts the Homebrew logrotate service |
setup-package-installation.sh |
Server | admin | Installs Homebrew and the formulae and casks from config/formulae.txt and config/casks.txt |
setup-power-management.sh |
Server | admin | Turns off system sleep, sets display sleep, turns on wake for network access and restart after power failure |
setup-remote-desktop.sh |
Server | admin (refuses root) | Turns off Screen Sharing and Remote Management, then guides you to turn Screen Sharing on by hand |
setup-shell-configuration.sh |
Server | admin | Makes Homebrew bash the login shell for the admin and operator accounts |
setup-ssh-access.sh |
Server | admin | Turns on Remote Login (SSH) and installs SSH keys for the admin and operator accounts |
setup-system-preferences.sh |
Server | admin | System preferences, such as Fast User Switching |
setup-terminal-profiles.sh |
Server | admin | Imports terminal profiles and makes them the default for the admin and operator accounts |
setup-timemachine.sh |
Server | admin | Sets the Time Machine SMB destination from keychain credentials |
setup-touchid-sudo.sh |
Server | admin | Turns on Touch ID for sudo and sets a temporary sudo timeout for setup |
setup-wifi-network.sh |
Server | admin | Checks and configures Wi-Fi, stores the password in the keychain, and tests the connection |
operator-first-login.sh |
Server | operator | One-time operator setup at first login: Dock, terminal profile, iTerm2, logrotate. Its LaunchAgent starts it. |
app-setup¶
run-app-setup.sh runs the setup scripts in dependency order. The scripts that refuse to run without root say so in the "Runs as" column.
| Path | Runs on | Runs as | Purpose |
|---|---|---|---|
run-app-setup.sh |
Server | admin | Runs the app-setup scripts in dependency order. --only SCRIPT runs one. --force passes --force to each script, which skips its prompts. |
rclone-setup.sh |
Server | admin | Installs the rclone config for operator and the Dropbox sync LaunchAgent |
podman-transmission-setup.sh |
Server | admin | Installs Podman, creates the transmission-vm machine, deploys the Transmission and PIA VPN container, the trigger watcher, the cleanup timer and the watchdogs |
filebot-setup.sh |
Server | admin | Installs FileBot, applies the license, and sets the rename formats and OpenSubtitles login |
transmission-filebot-setup.sh |
Server | The account that runs the pipeline | Interactive wizard: asks for the Plex server and token, writes ~/.config/transmission-done/config.yml, and links ~/.local/bin/transmission-done |
catch-setup.sh |
Server | admin | Installs Catch, sets its feed and save folder, and adds its LaunchAgent for operator |
plex-setup.sh |
Server | admin | NFS mount agents for the NAS media share, Plex install, optional migration from an earlier server, and the Plex LaunchAgent |
plex-watchdog-setup.sh |
Server | admin | Deploys the Plex settings watchdog, plex-watchdog-ctl, the golden config and the LaunchAgent |
msmtp-setup.sh |
Server | admin | Configures msmtp for operator as the shared alert email relay, and sends a test email |
caddy-setup.sh |
Server | root | Deploys the Caddyfile, web files, Caddy wrapper, media file server and their LaunchDaemons |
cloudflare-ddns-setup.sh |
Server | root | Deploys the Cloudflare DDNS updater and its LaunchDaemon |
cloudflared-setup.sh |
Server | root | Deploys the Cloudflare Tunnel wrapper and its LaunchDaemon |
access-policy-watchdog-setup.sh |
Server | root | Deploys the Access policy drift watchdog as an operator LaunchAgent |
tunnel-watchdog-setup.sh |
Server | root | Deploys the tunnel health watchdog as an operator LaunchAgent |
tvmaze-scrobble-setup.sh |
Server | root | Deploys the Plex to TVmaze listener, worker, credentials and two operator LaunchAgents |
app-setup/templates¶
The setup scripts copy these files to the server and fill in their __PLACEHOLDER__ tokens. "Sourced" means that the file defines functions for another script and runs nothing by itself.
| Path | Runs on | Runs as | Purpose |
|---|---|---|---|
access-policy-watchdog.sh |
Server | operator | Emails when the Cloudflare Access policy or tunnel config changes. --check prints the result only. |
alert-lib.sh |
Server | operator (sourced) | Shared alert email and JSON state helpers for the watchdogs |
caddy-health.sh |
Server | Any account, by hand | Tests the Caddy endpoints and the certificate, and reports the status |
caddy-wrapper.sh |
Server | root (LaunchDaemon) | Reads CF_API_TOKEN from the System keychain, then starts Caddy |
cloudflare-ddns.sh |
Server | root (LaunchDaemon) | Compares the public IP with the DNS A record and updates the record when they differ |
cloudflared-wrapper.sh |
Server | root (LaunchDaemon) | Reads the tunnel token from the System keychain into TUNNEL_TOKEN, then starts cloudflared |
media-compare.sh |
Server | operator (sourced) | Decides which of two copies of the same media to keep when FileBot renames onto an existing file |
mount-nas-media.sh |
Server | admin and operator (LaunchAgent) | Mounts the NAS media share over NFS for one account |
pending-move-cleanup.sh |
Server | operator (LaunchAgent) | Removes processed folders from Transmission's pending-move/ folder |
pia-pf-probe.sh |
Server | operator, by hand | Tests PIA regions for working port forwarding in a separate container, and writes CSV results |
pia-port-guard.sh |
Transmission container | Container (sourced) | Validates a PIA forwarded port before it is applied |
pia-port-watchdog.sh |
Server | operator (LaunchAgent) | Alerts when PIA port forwarding is lost |
plex-watchdog-ctl.sh |
Server | operator, by hand | Shows, accepts or reverts Plex settings drift (status, accept, revert) |
plex-watchdog.sh |
Server | operator (LaunchAgent) | Compares Plex preferences with the golden config, checks that Plex is alive, and emails on drift |
stable-sign.sh |
Server | admin (from the brew upgrade daemon, or by hand) | Keeps signed copies of Homebrew binaries at fixed paths under /usr/local/stable, so TCC grants survive brew upgrade. --check verifies them. |
stall-watchdog.sh |
Server | operator (LaunchAgent) | Alerts when the server is blocked: an open TCC prompt, a long transmission-done run, or a failing or quiet supervisor |
start-plex.sh |
Server | operator (LaunchAgent) | Starts Plex Media Server |
start-rclone.sh |
Server | operator (LaunchAgent) | Syncs a Dropbox folder to the local disk with rclone at a fixed interval |
transmission-done.sh |
Server | operator (from the trigger watcher) | Processes a completed download: runs FileBot, files the result in the media library, and asks Plex to scan |
transmission-post-done.sh |
Transmission container | Container | Writes a trigger file when a torrent finishes, for the host trigger watcher |
transmission-post-start.sh |
Transmission container | Container | Gets a PIA forwarded port, validates it, and applies it to Transmission. Replaces the image's own port updater. |
transmission-trigger-watcher.sh |
Server | operator (LaunchAgent) | Polls for trigger files from the container, maps the container path to the host path, and runs transmission-done.sh |
tunnel-watchdog.sh |
Server | operator (LaunchAgent) | Emails when the Cloudflare Tunnel is down. --check prints the result only. |
tvmaze-scrobble.sh |
Server | operator (LaunchAgent) | Marks a Plex TV episode watched on TVmaze. --reconcile syncs missed plays. |
media-server.py |
Server | operator (LaunchDaemon) | Serves directory listings and files from the NFS media mount on loopback, for Caddy's /media/ route |
tvmaze-scrobble-listener.py |
Server | operator (LaunchAgent) | Receives Plex webhooks on loopback and hands each one to tvmaze-scrobble |
process-media.command |
Server | operator, by hand | Runs transmission-done.sh from its folder in a Terminal window and shows the result |
Related pages¶
- LaunchAgents and LaunchDaemons: which jobs start these scripts.
- Logs: where each script writes.