Plex Setup Script Documentation¶
This document describes the plex-setup.sh script for Mac Mini server Plex Media Server setup.
Overview¶
The plex-setup.sh script automates native Plex Media Server deployment on macOS with:
- Native Plex Media Server installation via official macOS installer
- NFS mounting for NAS media storage access
- Shared configuration directory accessible to both admin and operator users
- LaunchAgent configuration for automatic startup with operator login
- SSH-based remote migration from existing Plex servers with server discovery
- Administrator setup with operator execution model
Usage¶
Script Path: ./app-setup/plex-setup.sh
Command Line Options:
--force: Skip all confirmation prompts--skip-migration: Skip Plex configuration migration--skip-mount: Skip NFS mount setup--server-name NAME: Set Plex server name (default:PLEX_SERVER_NAME_OVERRIDEfromconfig.confif set, else the hostname)--migrate-from HOST: Source hostname for Plex migration--custom-port PORT: Set custom port for fresh installations (prevents conflicts)--password PASSWORD: Provide administrator password for keychain operations
Examples:
# Full interactive setup with migration
./app-setup/plex-setup.sh
# Unattended fresh installation
./app-setup/plex-setup.sh --force --skip-migration
# Automated setup via orchestrator (uses --force)
./run-app-setup.sh
# Setup with custom server name
./app-setup/plex-setup.sh --server-name "MyPlexServer"
# Setup with automated migration
./app-setup/plex-setup.sh --migrate-from old-server.local
# Force mode with custom port to prevent conflicts
./app-setup/plex-setup.sh --force --custom-port 32401
Configuration¶
The script uses variables from config.conf:
SERVER_NAME="MEDIA" # Primary server identifier
OPERATOR_USERNAME="operator" # Auto-login service account (admin group)
NAS_HOSTNAME="nas.local" # NAS hostname for NFS
NAS_SHARE_NAME="Media" # Media share name
ONEPASSWORD_PLEX_NAS_ITEM="Plex NAS" # 1Password item for NAS credentials
Prerequisites¶
- Setup completed via first-boot.sh (includes credential import via keychain)
- No NAS credentials go into the mount scripts: the NFS mount uses host-based authentication (see Credential chain)
- For migration: Plex config files in
~/plex-migration/Plex Media Server/
Architecture¶
Setup Process¶
- Admin setup:
plex-setup.shruns as administrator - Installs Plex Media Server application
- Configures NFS mount scripts (NFS uses host-based auth, no credentials embedded)
- Creates shared configuration directory (
/Users/Shared/PlexMediaServer) - Migrates existing Plex configuration if requested
- Links
/Users/Shared/PlexMediaServer/Plex Media Serverto the real data in~operator/Library/Application Support/Plex Media Server(ensure_plex_data_link; see "Data directory link" inplex-watchdog.md) -
Deploys LaunchAgent and mount scripts to operator account
-
Operator runtime: Automatic on operator login
- LaunchAgent starts Plex with shared configuration
- NFS mount provides media access (host-based auth, no credentials needed)
- Plex runs under operator account
File Locations¶
- Application:
/Applications/Plex Media Server.app - Plex data:
~operator/Library/Application Support/Plex Media Server/ - Shared config:
/Users/Shared/PlexMediaServer/. ItsPlex Media Serverentry is a link to the Plex data. It must never be a real directory: Plex started by the LaunchAgent would run an empty server from it. - Mount script:
~/.local/bin/mount-nas-media.sh - LaunchAgent:
~/Library/LaunchAgents/com.${HOSTNAME_LOWER}.plexmediaserver.plist - Media mount:
~/.local/mnt/${NAS_SHARE_NAME}
Log Locations¶
- Setup logs:
~/.local/state/${HOSTNAME_LOWER}-apps.log - Plex logs:
~operator/Library/Logs/Plex Media Server/ - LaunchAgent log:
~operator/.local/state/${HOSTNAME_LOWER}-plex-launchagent.log(stdout and stderr)
Migration¶
Preparing Migration Files¶
From existing macOS Plex server:
# Stop Plex and copy config (excluding Cache)
rsync -av --exclude='Cache' "~/Library/Application Support/Plex Media Server/" ~/migration-backup/
# Transfer to new server at ~/plex-migration/
The script supports both local migration (files in ~/plex-migration/) and remote migration via SSH.
SSH Security for Migration¶
SSH Host Key Verification: For automated migration workflows, the script uses StrictHostKeyChecking=no to prevent blocking on unknown host keys during server-to-server transfers. This is intentional for migration scenarios where:
- Target server may not have established SSH relationships with source servers
- Migration typically occurs between trusted servers on the same network
- Automation workflows need to proceed without manual intervention for host key acceptance
Security Context: This setting is used specifically for:
- Migration connection testing:
ssh -o StrictHostKeyChecking=no -o ConnectTimeout=5 -o BatchMode=yes - Automated file transfers during configuration migration
- One-time setup operations between known server pairs
Note: This does not affect ongoing SSH security for regular server operations, which continue to use standard SSH host key verification.
Post-Migration: Home Screen Setup¶
⚠️ Important: After migrating from an existing Plex server, you may need to re-pin your media sources to the home screen.
What happens during migration:
- Server configuration and libraries migrate successfully
- Server gets a new name to prevent conflicts with the source server
- Your Plex account recognizes this as a "different" server
- Previously pinned sources become unavailable and disappear from the home screen
To restore your home screen:
- Access your new Plex server via web interface
- Click "More" in the sidebar navigation
- Find your migrated libraries (they're still there, just not pinned)
- Click the pin icon next to each library you want on your home screen
- Your customized home screen will be restored
This is a one-time setup step that ensures proper server identity while both old and new servers may be running simultaneously during migration.
Port Conflict Prevention¶
Critical Network Port Issue¶
⚠️ IMPORTANT: If you have an existing Plex server running on your network using the default port 32400, installing a new Plex server without migration can cause serious network conflicts.
The Problem:
- Existing Plex server uses port 32400 (default)
- New Plex installation also tries to use port 32400 (default)
- UPnP/Auto-port mapping conflicts occur at the router level
- Result: External access to your existing Plex server may be blocked
Scenarios:
✅ SAFE - Migration Mode:
# When migrating, ports are automatically managed
./app-setup/plex-setup.sh --migrate-from old-server.local
# Result: Source keeps 32400, target gets 32401 automatically
# No conflicts, both servers accessible
⚠️ RISKY - Fresh Installation:
# Without migration, both servers try to use port 32400
./app-setup/plex-setup.sh --skip-migration
# Result: Network port conflicts likely
# May block access to existing Plex server
Migration Benefits:
- Automatic port detection: Script detects source server port via SSH
- Smart port assignment: Target gets source port + 1 (e.g., 32400 → 32401)
- Router guidance: Detailed instructions for updating port forwarding
- Zero conflicts: Both servers can run simultaneously during transition
Automation Mode (--force)¶
When plex-setup.sh is run with the --force flag (including when called via run-app-setup.sh), it operates in automation mode with specific behavior:
Automatic Decision Making¶
✅ Auto-Confirmed (Default "y"):
- Initial setup confirmation: "Set up Plex Media Server?" → YES
❌ Auto-Declined (Default "n"):
- Migration prompt: "Do you want to migrate from an existing Plex server?" → NO
- Custom port prompt: "Do you want to use a custom port instead of 32400?" → NO
- Configuration migration: "Apply migrated Plex configuration?" → NO
Port Conflict Behavior¶
Important: In --force mode, Plex setup always uses port 32400 unless explicitly overridden:
# Default automation behavior - uses port 32400
./run-app-setup.sh
./app-setup/plex-setup.sh --force
# Result: May conflict with existing Plex servers on network
Enhanced Logging: When --force mode skips custom port selection, the script provides detailed guidance:
⚠️ Using default port 32400 in automation mode
⚠️ If port conflicts occur with existing Plex servers:
• Rerun with: --custom-port 32401 (or other available port)
• Check for other Plex servers: dns-sd -B _plexmediasvr._tcp
• Or use run-app-setup.sh --only plex-setup.sh for interactive setup
Resolving Port Conflicts in Automation¶
Option 1: Command-line override:
Option 2: Interactive mode for single app:
Option 3: Detect existing servers:
# Check for Plex servers on network before automation
dns-sd -B _plexmediasvr._tcp
# If servers found, use --custom-port
Still Interactive Elements¶
Even in --force mode, these elements remain interactive:
- Administrator password: Required for keychain access and sudo operations
- Server discovery: When migration is manually specified via
--migrate-from - Plex application launch: GUI application startup requires user session
Server Update Policy¶
Plex updates itself, unattended. configure_plex_updates sets Settings →
General → Server version updates to "Automatically during scheduled
maintenance" (ButlerTaskUpdateServer=always), so an update installs
between ButlerStartHour and ButlerEndHour (00:00–08:00 here).
That only works because the operator owns the app. Plex's updater runs as
the operator and first tries to write a test file into
/Applications/Plex Media Server.app. Until 2026-10-22 the app was owned
by root, so that failed and the updater asked for an admin password in a
GUI prompt:
checkAccess() on /Applications/Plex Media Server.app/_plexUpdaterTestFile failed ... Permission denied
Insufficient rights to install app to /Applications/Plex Media Server.app requesting elevation
Plex had already stopped by then. With no one at the desktop it stayed
down until someone answered, which is why the setting used to be "Ask me".
Every update in update-log.txt up to 1.43.4 went through that prompt.
configure_plex_updates runs chown -R operator:staff on the app;
updates the updater installs keep that owner.
The trade-off: the operator account can change the Plex binary. It already controls everything Plex runs with (data, LaunchAgent), so this adds little.
Homebrew no longer upgrades Plex. The daily brew upgrade
(scripts/server/setup-auto-updates.sh) skips the plex-media-server
cask (SKIP_CASKS). On 2026-10-21 it tried to replace the running app,
failed because Plex's elevated updater had left the app owned by root,
and left a copy in the Caskroom that made every later run fail with "It seems there is already
an App". The plex-watchdog does not restart Plex while an update may be
running; see plex-watchdog.md.
Check the last update with:
Manual Operations¶
Service Management¶
# Check Plex status
launchctl print gui/$(id -u)/com.${HOSTNAME_LOWER}.plexmediaserver
ps aux | grep "Plex Media Server"
# Restart Plex
launchctl kickstart -kp gui/$(id -u)/com.${HOSTNAME_LOWER}.plexmediaserver
# View logs
tail -f ~/.local/state/${HOSTNAME_LOWER}-apps.log
tail -f ~operator/.local/state/${HOSTNAME_LOWER}-plex-launchagent.log
# Check NAS mount
mount | grep ${NAS_SHARE_NAME}
ls ~/.local/mnt/${NAS_SHARE_NAME}
NFS Mount Management¶
# Manual mount test
~/.local/bin/mount-nas-media.sh
# Check mount LaunchAgent
launchctl list | grep mount-nas-media
# View mount logs
tail -f ~/.local/state/${HOSTNAME_LOWER}-mount.log
Troubleshooting¶
Error Collection and Summary¶
The Plex setup script includes comprehensive error and warning collection:
- Real-time display: Errors and warnings show immediately during setup
- End-of-run summary: Consolidated review of all issues when setup completes
- Context tracking: Each issue shows which setup section it occurred in
Example summary output:
====== PLEX SETUP SUMMARY ======
Plex setup completed, but 1 error and 2 warnings occurred:
ERRORS:
❌ Installing Plex Media Server: Homebrew installation failed
WARNINGS:
⚠️ Setting Up Per-User NFS Mount: Admin NFS mount failed - check NAS NFS export
⚠️ Configuring Remote Migration: SSH connection to old-server.local failed
Review the full log for details: ~/.local/state/macmini-apps.log
Common Issues¶
1Password CLI Issues:
NAS Mount Failures:
# Test connectivity and the NFS export (NFS uses no credentials)
ping ${NAS_HOSTNAME}
showmount -e ${NAS_HOSTNAME}
# Manual NFS mount test
sudo mount_nfs -o resvport,rw,soft your-nas.local:/volume1/Media ~/.local/mnt/${NAS_SHARE_NAME}
# Check NFS exports from NAS
showmount -e ${NAS_HOSTNAME}
Shared Config Access Issues:
# Check permissions
ls -la /Users/Shared/PlexMediaServer/
groups ${OPERATOR_USERNAME}
# Fix permissions
sudo chown -R admin:staff /Users/Shared/PlexMediaServer/
sudo chmod -R 775 /Users/Shared/PlexMediaServer/
sudo dseditgroup -o edit -a ${OPERATOR_USERNAME} -t user staff
LaunchAgent Issues:
# Reload LaunchAgent
launchctl bootout gui/$(id -u)/com.${HOSTNAME_LOWER}.plexmediaserver
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.${HOSTNAME_LOWER}.plexmediaserver.plist
# Check LaunchAgent file
cat ~/Library/LaunchAgents/com.${HOSTNAME_LOWER}.plexmediaserver.plist
Reset and Reinstall¶
# Clean reinstall
sudo rm -rf "/Applications/Plex Media Server.app"
sudo rm -rf /Users/Shared/PlexMediaServer
rm -f ~/Library/LaunchAgents/com.${HOSTNAME_LOWER}.plexmediaserver.plist
# Re-run setup
./app-setup/plex-setup.sh
Post-Setup Configuration¶
⚠️ Important: After successful Plex setup, you should review and configure your Plex server settings to match your preferences. The setup script automates the basic installation and media access, but many personalization settings require manual configuration.
Required Manual Configuration¶
Access your Plex server at http://your-server.local:32400 and review these settings:
Server Settings → General¶
- Server name: Verify the automatically configured name
- Language and region: Set your preferred language and country
- Remote access: Configure if you need external access to your server
Server Settings → Library¶
- Add media libraries: Point to your mounted media directories (
~/.local/mnt/Media/...) - Library naming: Customize library names (Movies, TV Shows, Music, etc.)
- Scanner settings: Configure metadata agents and scanner options
- Artwork and metadata: Set preferred metadata and artwork sources
Server Settings → Network¶
- Remote access: Enable/disable and configure port forwarding if needed
- LAN networks: Add your local network ranges for better security
- Advanced networking: Configure if you have complex network requirements
Server Settings → Transcoder¶
- Transcoder quality: Set hardware acceleration preferences (Apple Silicon supports hardware transcoding)
- Background transcoding: Configure optimization schedules
- Bandwidth limits: Set streaming quality limits if needed
Server Settings → Scheduled Tasks¶
- Library maintenance: Configure automatic library updates
- Media optimization: Set up background video optimization
- Backup schedules: Configure automatic database backups
User-Specific Preferences¶
Account Settings¶
- Privacy settings: Configure data sharing and analytics preferences
- Sharing settings: Set up user access and sharing permissions
- Online media sources: Configure or disable online content integration
Playback Settings¶
- Quality settings: Default streaming quality for different connection types
- Subtitle settings: Default subtitle preferences and fonts
- Audio settings: Default audio track preferences
Optional Advanced Configuration¶
Webhooks and Notifications¶
- Plex webhook: Configure external service integrations
- Mobile notifications: Set up push notifications for mobile apps
DLNA and External Players¶
- DLNA server: Enable if you have DLNA devices on your network
- External player support: Configure for specialized media players
Media Scanner Settings¶
- File detection: Configure how often libraries are scanned for new content
- Metadata refresh: Set automatic metadata update intervals
Integration with Media Pipeline¶
If you're using the complete media pipeline (Transmission → FileBot → Plex), verify:
- Media library paths point to the final processed media locations
- FileBot output directories match Plex library scan paths
- Transmission completion scripts are properly moving files to Plex-monitored directories
Testing Your Configuration¶
After configuration:
- Add test content to verify library scanning works
- Test playback on different devices to verify transcoding
- Check mobile access if remote access is enabled
- Verify media pipeline by downloading test content through the full workflow
The script integrates with the server's configuration system and follows the administrator-setup, operator-execution model used throughout the project.