Skip to content

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:

  • --force skips the confirmation prompts. Do not use it on a first run; see Run first boot.
  • --skip-homebrew skips the Homebrew install and configuration.
  • --skip-packages skips the formulae and casks in config/formulae.txt and config/casks.txt.
  • --skip-update is 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