📜 Scripts Management Process#

Workstation Sync Shortcut: To automatically backup all your scripts and custom terminal aliases configuration (staging and pushing your entire ~/Scripts/ repository):
pushscripts
This will stage all modified files in ~/Scripts/, commit, and push updates directly to GitHub and your NAS (without running Homebrew operations).

Workstation Update Shortcut: To pull down the latest custom scripts and terminal aliases from GitHub on an existing machine (after the first-time setup is complete):
pullscripts
This will run git pull on your scripts repository to keep your code environment up-to-date.

Quick Clone & Restore (Secondary Computer): To restore your entire configuration and scripts environment on a new machine with a single line:
git clone git@github.com:marcoue/Scripts.git ~/Scripts && source ~/Scripts/MacOS/Aliases/MacOS_Aliases_restore.sh
This will download your scripts repository and trigger the profile utility to set up your local ~/.zshrc profile.

Quick Sync / Update (Existing Workstation - First Time): To transition an existing machine to the new layout (or pull updates manually when the alias is not yet loaded):
cd ~/Scripts && git pull && source ~/Scripts/MacOS/Aliases/MacOS_Aliases_restore.sh && source ~/.zshrc
This pulls the latest repo changes, rewrites/reloads the local ~/.zshrc profile, and refreshes the shell session, enabling the new pullscripts and pushscripts aliases for all future runs.

This document is the authoritative, long-term operational standard for authoring, version-controlling, distributing, and executing scripts across the homelab infrastructure.

1. Core Architecture & Philosophy#

All homelab scripts are managed under a single-source-of-truth architecture designed for centralized editing, automatic distribution, and hardware independence.

🎯 The Four Architectural Pillars#

Master Workstation Repository: /Users/marc/Scripts on the Mac Studio is the primary master workspace where all scripts are authored, edited, tested, and version-controlled.
Cloud Version Control: Linked to GitHub remote git@github.com:marcoue/Scripts.git on branch main.
Automated Distribution Mirror: A local Git post-commit hook automatically mirrors committed scripts from Mac Studio (~/Scripts/) to UNAS-Pro NAS (/Volumes/Software/Software/Scripts/).
Independent Server Execution: Remote nodes pull or execute their versioned scripts from the central distribution mirror or local dataset copies.

  ┌────────────────────────────────────────────────────────┐
  │         Mac Workstation (Master Workspace)             │
  │                  ~/Scripts/                            │
  │     (Linked to git@github.com:marcoue/Scripts.git)     │
  └──────────────────────────┬─────────────────────────────┘
                             │
                             │ (git commit)
                             ▼
  ┌────────────────────────────────────────────────────────┐
  │                Git post-commit Hook                    │
  │       (rsync auto-mirror to mounted SMB share)         │
  └──────────────────────────┬─────────────────────────────┘
                             │
                             ▼
  ┌────────────────────────────────────────────────────────┐
  │            UNAS-Pro NAS (Distribution Mirror)          │
  │            /Volumes/Software/Software/Scripts/         │
  │        (Exposed as Rsync Module: ::Software)           │
  └──────────────────────────┬─────────────────────────────┘
                             │
                             │ (Rsync / Git pull on schedule)
                             ▼
  ┌────────────────────────────────────────────────────────┐
  │          Remote Server Nodes (TrueNAS, PVE, Linux)     │
  │           Execution of Version-Controlled Scripts      │
  └────────────────────────────────────────────────────────┘

2. Directory Structure & Categorization Standard#

The repository uses standardized platform subdirectories. Every script MUST be placed into its appropriate category folder:

/Users/marc/Scripts/
├── MacOS/       # Workstation automation, local syncs, KVM launchers, utility tools
│   ├── Aliases/ # Managed shell configurations (MacOS-Aliases.zsh and restore utility)
│   └── Brew/    # Workstation package lists (Brewfile)
├── Linux/       # General Linux server utilities, speed tests, web publishing
├── Proxmox/     # Proxmox VE node/VM backup, restore, and cluster utilities
│   └── Archives/# Retained legacy / reference scripts
└── TrueNAS/     # TrueNAS node standalone backup scripts

📋 Organization Rules:#

MacOS/: Scripts designed to run locally on macOS workstations (e.g., Hugo note syncs, image processing, desktop utilities). Package lists and aliases are structured under Brew/ and Aliases/ subdirectories.
Linux/: Scripts designed for general Linux servers, container environments, or distribution tasks.
Proxmox/: Scripts designed specifically for Proxmox VE hypervisors and PBS/PVE operations.
[TrueNAS](TrueNAS.md)/: Scripts designed specifically for TrueNAS storage nodes and zfs/midclt operations.

3. Development & Deployment Workflow#

Follow this standard 3-step workflow whenever creating or modifying scripts:

Step 1: Write & Test Locally (Mac Studio)#

Create or edit the script inside /Users/marc/Scripts/<Category>/<script_name>.sh. Grant executable permissions before committing:

chmod +x /Users/marc/Scripts/<Category>/<script_name>.sh

Step 2: Commit & Push to GitHub#

Commit the change to version control:

cd /Users/marc/Scripts
git add .
git commit -m "Describe script updates"
git push origin main

Workstation Sync Shortcut: For quick workstation updates, you can run the pushscripts alias from your terminal. It will automatically stage all changes in your scripts repository, commit them, and push them to GitHub.

Step 3: Automated NAS Distribution (Hands-Free)#

Upon executing git commit, the local Git post-commit hook automatically fires and mirrors the updated scripts to the NAS distribution share (/Volumes/Software/Software/Scripts/).

🔧 Git Hook Implementation (`~/Scripts/.git/hooks/post-commit`):#

#!/usr/bin/env bash
# Git post-commit hook: Auto-mirror ~/Scripts to UNAS-Pro SMB Share
if [ -d "/Volumes/Software/Software/Scripts" ]; then
    echo "=== Git Hook: Auto-mirroring ~/Scripts to UNAS-Pro NAS ==="
    rsync -av --delete --exclude='.git' --exclude='*.log' /Users/marc/Scripts/ /Volumes/Software/Software/Scripts/
else
    echo "⚠️ Warning: UNAS-Pro SMB Share (/Volumes/Software) not mounted. Mirror skipped."
fi

4. Execution & Permission Best Practices#

When scripts are synced across network storage shares (SMB/NFS), POSIX executable permissions (+x) can be stripped or mapped to default read/write modes (-rw-rw---- / 660). Attempting to execute a script directly via ./script.sh or /path/to/script.sh on network-mounted or pulled files may fail with Permission denied (13).

The Explicit Interpreter Rule#

To guarantee 100% execution reliability across all environments, scheduled tasks and automated jobs MUST invoke scripts using their explicit interpreter:

Shell Scripts:
```
bash /path/to/script.sh
```
Python Scripts:
```
python3 /path/to/script.py
```

Executing via an explicit interpreter (e.g., bash /path/to/script.sh) only requires read permission (r) on the file, eliminating reliance on the Unix executable +x bit completely.

5. Workstation Recovery & Disaster Protocol#

The script management architecture is completely decoupled from local workstation hardware. Reinstalling or replacing macOS on your Mac Studio causes ZERO disruption to NAS distribution storage or remote server execution.

🔄 Workstation Restoration Guide (New Mac / Reinstall)#

To restore your script management environment on a fresh macOS installation:

Mount NAS SMB Share: Connect to smb://10.1.2.2/Software and add /Volumes/Software to System Settings > General > Login Items.

Clone Master Repository from GitHub:

git clone git@github.com:marcoue/Scripts.git ~/Scripts

Re-install Git Auto-Mirroring Hook:

cat << 'EOF' > ~/Scripts/.git/hooks/post-commit
#!/usr/bin/env bash
if [ -d "/Volumes/Software/Software/Scripts" ]; then
    echo "=== Git Hook: Auto-mirroring ~/Scripts to UNAS-Pro NAS ==="
    rsync -av --delete --exclude='.git' --exclude='*.log' /Users/marc/Scripts/ /Volumes/Software/Software/Scripts/
fi
EOF
chmod +x ~/Scripts/.git/hooks/post-commit

Verify Environment: Run git status in ~/Scripts/ to confirm tracking origin/main.

5.5 Complete Scripts Inventory#

Below is a complete index of all scripts managed in the ~/Scripts repository:

🍏 macOS Scripts (`MacOS/`)#

Script	Alias	Description
`Aliases/MacOS_Aliases_restore.sh`	—	Bootstraps workstation profile and restores `~/.zshrc`.
`KVM-Launch.sh`	`kvm`	Launches the Java Web Start utility for the Tripp Lite KVM switch.
`git_status.py`	`gitstatus`	Reports Git repository status information.
`Rclone-MarcGoogleDrive.sh`	—	Runs rclone backup syncs with personal Google Drive storage.
`ai_deploy_safety_on_all_servers.sh`	—	Automates deploying AI safety configuration files to all remote servers.
`convert_images_1024.sh` / `convert_images_900.sh`	`convert` (900px script)	Resizes local image assets to 1024px or 900px width.
`convert_images_jpg.sh` / `convert_images_raw_jpg.sh`	—	Converts images and RAW files to standard JPG formats.
`convert_images_to_1260X2736px.sh`	—	Resizes images to exactly 1260x2736px.
`convert_raw_send_to_vm.sh`	`convertsend`	Converts raw image directories and uploads them to the target Proxmox VM.
`convert_rename_images_raw_jpg.sh`	—	Converts RAW files, renames files sequentially, and outputs JPGs.
`file_indexer.sh`	—	Indexes directory structures into plain text catalog maps.
`generate_favicons.sh`	—	Generates multi-size web favicon assets from a master image.
`ios_icon_maker.sh`	—	Generates all app icon sizes required for iOS device layouts.
`lock_gendash.sh`	`genl`, `genu`, `gens`, `genx`	Manages collaborative edit locking/unlocking for GenDash project strings.
`post-commit-hook.sh`	—	Backup copy of the Git hook that mirrors the `~/Scripts` repo to the NAS.
`speed_test.sh`	`speed`	Runs network speed and ping diagnostic tests.
`sync-gemini-to-macbook15.sh` / `sync-gemini-to-macbookair.sh` / `sync-gemini-to-macstudio.sh`	—	Synchronizes Gemini config files to MacBook 15, MacBook Air, and Mac Studio respectively.
`sync-obsidian-gendash-hugo.sh` / `sync-obsidian-homelab-hugo.sh` / `sync-obsidian-peru-hugo.sh`	`pushgen`, `pushlab` (respective scripts)	Syncs Obsidian notes to Linux VM for Hugo hosting.

🐧 Linux Scripts (`Linux/`)#

Script	Alias	Description
`RN-VPSPangoling_pull_backups.sh`	—	Pulls backups from VPS Pangoling.
`RN-VPSPangoling_pull_backups_integrity_check.sh`	—	Checks backup file integrity for VPS Pangoling.
`publish-hugo-gendash.sh`	—	Builds and publishes GenDash site using Hugo on Linux VM.
`publish-hugo-homelab.sh`	—	Builds and publishes Homelab site using Hugo on Linux VM.
`setup_ai_safety.sh`	—	Configures AI safety configurations on Linux hosts.
`speed.sh` / `speed_2.sh`	—	Runs network speed diagnostic tests.
`Netbox/Netbox_import.py`	—	Python script to import devices/assets into NetBox.
`Netbox/Netbox_sync_gsheets_to_netbox.py`	`netbox`	Synchronizes Google Sheets inventory records into NetBox database.

🛡️ Proxmox Scripts (`Proxmox/`)#

Script	Alias	Description
`proxmox_backup.sh`	—	Manages backup tasks for Proxmox VE nodes.
`proxmox_restore.sh`	—	Handles restore routines for Proxmox VE containers/VMs.

💾 TrueNAS Scripts (`TrueNAS/`)#

Script	Alias	Description
`HP1_UNAS_Pull_Backup.sh` / `HP2_UNAS_Pull_Backup.sh` / `HP3_UNAS_Pull_Backup.sh` / `HP7_UNAS_Pull_Backup.sh` / `HP8_UNAS_Pull_Backup.sh`	—	Standalone backup pull scripts matching TrueNAS storage nodes.

6. Operational Reference Links#

Master Recovery Checklist: Mac OS - Recovery
Workstation Software Inventory: Mac OS - Brewfile
Zsh Shortcut Configurations: Mac OS - Aliases Management
Linux Server Shortcuts: Linux - Aliases
Backup Migration Plan: Unifi UNAS-Pro Backup Migration Plan
Scripts Migration Log: Scripts Management Migration Plan
GitHub Remote Repository: git@github.com:marcoue/Scripts.git