macOS Update Notifier

A proactive email notification system for MacAdmins to ensure timely macOS updates across their fleet

🎯 What is this?

As a MacAdmin, you know the challenge: users tend to ignore macOS update notifications that appear on their screens, but they actually read and respond to emails. The macOS Update Notifier bridges this gap by sending timely email notifications when macOS updates are released and installation deadlines are approaching.

The Problem

System notifications get dismissed or ignored
Users postpone updates indefinitely
Critical security updates are delayed
Compliance requirements are missed

The Solution

Email notifications that users actually read
Customizable installation deadlines per user/group
Automated monitoring of macOS releases
Professional email templates with clear instructions
Multi-admin management with role-based access

🚀 Key Features

For MacAdmins

📊 Administrative Dashboard: Overview of subscribers, recent releases, and system statistics
👥 User Management: Super admin and regular admin roles with appropriate access controls
📧 Bulk Import: Import subscribers via CSV upload or copy/paste from spreadsheets
📈 Activity Tracking: Monitor subscriber actions and notification history
🔄 Automated Monitoring: Daily checks for new macOS releases from the SOFA feed

For End Users

📬 Timely Notifications: Email alerts when updates are available and deadlines approach
⚙️ Self-Service Options: Links to update preferences or unsubscribe
📝 Clear Instructions: Step-by-step update installation guidance
⏰ Deadline Awareness: Clear communication about installation deadlines

Technical Features

🔐 Secure Authentication: Magic link login system (no passwords to manage)
📱 Responsive Design: Modern glassmorphism UI that works on all devices
🗃️ SQLite Database: No complex database setup required – but available when needed
⚡ Background Jobs: Efficient processing of notifications and data fetching
🧪 Comprehensive Testing: 190+ tests ensuring reliability

🏗️ Architecture Overview

┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   SOFA Feed     │───▶│  Update Notifier │───▶│   Email Server   │
│ (macOS Releases)│    │     (Laravel)    │    │    (SMTP/SES)    │
└─────────────────┘    └──────────────────┘    └──────────────────┘
                                 ▲                      │
                                 │                      ▼
                       ┌──────────────────┐    ┌──────────────────┐
                       │    Mac Admins    │    │   Subscribers    │
                       │   (Web Access)   │    │  (Email client)  │
                       └──────────────────┘    └──────────────────┘

How It Works

Daily Monitoring: System fetches latest macOS releases from the SOFA feed
Deadline Calculation: Calculates installation deadlines based on subscriber preferences
Smart Notifications: Sends emails only when deadlines are approaching (configurable threshold)
User Actions: Subscribers receive emails with clear instructions and self-service options

📋 Prerequisites

Before installing, ensure you have:

Web Server: Apache, Nginx, or development server
PHP 8.2+ with extensions:
- SQLite PDO (for database)
- cURL (for fetching releases)
- OpenSSL (for security)
- Mbstring (for email handling)
Composer (PHP dependency manager)
Email Service: SMTP server, AWS SES, or similar
NPM: for frontend compilation

💡 For Non-Developers: If these terms are unfamiliar, consider using a hosting service like Laravel Forge or DigitalOcean App Platform that handles the technical setup.

🛠️ Installation

Method 1: Quick Start (Recommended for Testing)

# 1. Download the project
git clone https://github.com/wycomco/macos-update-notifier.git
cd macos-update-notifier

# 2. Install dependencies
composer install

# 3. Setup environment
cp .env.example .env
php artisan key:generate

# 4. Create database
touch database/database.sqlite
php artisan migrate

# 5. Start the development server
php artisan serve

Visit http://localhost:8000 to access the application.

Method 2: Production Deployment

For production use, consider these hosting options:

Option A: Laravel Forge (Easiest)

Sign up for Laravel Forge
Connect your server (DigitalOcean, AWS, etc.)
Deploy directly from your GitHub repository
Forge handles SSL, database, and server configuration

Option B: Manual Server Setup

Configure your web server (Apache/Nginx)
Set up SSL certificates
Configure scheduled tasks (cron)
Set up process monitoring (Supervisor)

📖 Detailed deployment guides are available in the Laravel documentation.

⚙️ Configuration

1. Environment Setup

Edit your .env file with these essential settings:

# Application
APP_NAME="macOS Update Notifier"
APP_URL=https://your-domain.com

# Database (SQLite - no setup required)
DB_CONNECTION=sqlite

# Email Configuration (REQUIRED)
MAIL_MAILER=smtp
MAIL_HOST=smtp.your-provider.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-app-password
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="macOS Update Team"

# macOS Notifier Settings
SOFA_FEED_URL=https://sofafeed.macadmins.io/v1/macos_data_feed.json
DEFAULT_DAYS_TO_INSTALL=30
NOTIFICATION_WARNING_DAYS=7

2. Email Service Setup

Choose your email provider:

Gmail/Google Workspace

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-app-password  # Use App Password, not regular password

Microsoft 365

MAIL_MAILER=smtp
MAIL_HOST=smtp.office365.com
MAIL_PORT=587
MAIL_USERNAME=[email protected]
MAIL_PASSWORD=your-password

AWS SES (Scalable)

MAIL_MAILER=ses
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_DEFAULT_REGION=us-east-1

3. Super Admin Setup

Create your first admin account:

php artisan tinker

use App\Models\User;

User::create([
    'name' => 'Your Name',
    'email' => '[email protected]',
    'password' => bcrypt('temporary-password'),
    'is_super_admin' => true
]);

4. Automated Tasks

For production, set up the Laravel scheduler:

# Add to your server's crontab
crontab -e

# Add this line:
* * * * * cd /path/to/your/project && php artisan schedule:run >> /dev/null 2>&1

For development/testing:

php artisan schedule:work

5. Queue Worker Setup (Required for Production)

The application uses background jobs for email processing and other tasks. In production, you must run a queue worker:

Option A: Using Supervisor (Recommended for Production)

Create a supervisor configuration file /etc/supervisor/conf.d/macos-notifier.conf:

[program:macos-notifier-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /path/to/your/project/artisan queue:work --sleep=3 --tries=3 --max-time=3600
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/path/to/your/project/storage/logs/worker.log
stopwaitsecs=3600

Then start the supervisor service:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start macos-notifier-worker:*

Option B: Using systemd

Create a systemd service file /etc/systemd/system/macos-notifier-queue.service:

[Unit]
Description=macOS Update Notifier Queue Worker
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/your/project
ExecStart=/usr/bin/php artisan queue:work --sleep=3 --tries=3 --max-time=3600
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable macos-notifier-queue
sudo systemctl start macos-notifier-queue

Option C: Development/Testing

For development or testing environments, you can run the queue worker manually:

php artisan queue:work

⚠️ Important: Without a queue worker running, emails will not be sent and other background tasks will not execute. The application will appear to work but notifications will remain in the queue.

👥 User Management

Admin Roles

Super Admin

Full System Access: Manage all users and subscribers
User Management: Create, promote, demote, and delete admin accounts
System Overview: View system-wide statistics and all subscriber data
Settings Control: Configure system-wide settings

Regular Admin

Subscriber Management: Manage only their assigned subscribers
Limited Dashboard: View only their subscriber statistics
No User Access: Cannot manage other admin accounts

Adding Subscribers

Method 1: Individual Entry

Navigate to Subscribers → Add New
Fill in subscriber details
Select macOS versions to monitor
Set installation deadline (days after release)

Method 2: Bulk Import

Navigate to Subscribers → Bulk Import
Choose your method:
- CSV Upload: Upload a properly formatted CSV file
- Copy/Paste: Paste data directly from Excel/Sheets
Configure import settings:
- macOS Versions: Select which versions to monitor
- Days to Install: Set notification deadline (1-365 days)
- Language: Choose notification language (optional, defaults to English)

CSV Format Example

email,subscribed_versions,days_to_install
[email protected],"macOS 14,macOS 15",30
[email protected],"macOS 15",14
[email protected],"macOS 14,macOS 15",60

Language Support

English (en) - Default
German (de) - Deutsch
French (fr) - Français
Spanish (es) - Español

All imported subscribers will use the selected language for notifications. If no language is specified, English will be used as the default.

📧 Email Notifications

When Notifications Are Sent

Emails are automatically sent when:

New Release Available: A macOS update is published for subscribed versions
Deadline Approaching: Installation deadline is within the warning period (default: 7 days)
Critical Updates: Security updates with shorter installation windows

Email Content Includes

Release Information: Version number, release date, and key features
Personal Deadline: User's specific installation deadline
Installation Instructions: Step-by-step update guide
Self-Service Links: Update preferences or unsubscribe options
Company Branding: Customizable sender name and styling

Customization Options

Administrators can modify:

Notification Timing: Adjust warning periods in .env
Sender Information: Company name and email address
Installation Deadlines: Per-subscriber customization

📊 Dashboard & Analytics

Super Admin Dashboard

System Overview: Total subscribers, active admins, recent releases
User Performance: Admin activity and subscriber management stats
Version Distribution: Breakdown of subscribers by macOS version
Recent Activity: Latest system actions and notifications

Regular Admin Dashboard

Subscriber Summary: Count and status of managed subscribers
Version Breakdown: Distribution of subscribed macOS versions
Recent Actions: Latest subscriber activity and notifications
Quick Actions: Add subscribers, bulk import, view reports

Reports Include

Notification History: Track what emails were sent and when
Subscriber Activity: Monitor user interactions and preferences
System Health: Database status, email queue, and error tracking

🔧 Maintenance & Monitoring

Daily Operations

The system automatically handles:

Release Monitoring: Checks SOFA feed for new macOS versions
Notification Processing: Sends emails for approaching deadlines
Database Cleanup: Removes old logs and temporary data

Manual Operations

Check for Updates Immediately

php artisan macos:check-updates

Test Email Configuration

php artisan macos:check-updates [email protected]

View System Status

php artisan macos:status

Monitoring & Logs

Application Logs

tail -f storage/logs/laravel.log

Email Queue Status

php artisan queue:status

Queue Worker Management

Check if your queue worker is running:

# For supervisor
sudo supervisorctl status macos-notifier-worker:*

# For systemd
sudo systemctl status macos-notifier-queue

# View recent queue jobs
php artisan queue:failed

If emails aren't being sent, restart the queue worker:

# For supervisor
sudo supervisorctl restart macos-notifier-worker:*

# For systemd
sudo systemctl restart macos-notifier-queue

# Or manually restart
php artisan queue:restart

Database Health

The system uses SQLite by default, requiring minimal maintenance. For high-volume deployments, consider migrating to PostgreSQL or MySQL.

🔧 Troubleshooting

Common Issues

No releases found: Check the SOFA feed URL and internet connectivity
Emails not sending:
- Verify mail configuration in .env
- Check if queue worker is running (most common issue)
- Review queue logs for failed jobs
Scheduled tasks not running: Ensure schedule:work is running or cron is configured
Background jobs failing: Check queue worker logs and restart if necessary

Queue Troubleshooting

If notifications aren't being sent:

Check queue worker status:

# View queue status
php artisan queue:status

# Check for failed jobs
php artisan queue:failed

Test email sending manually:

# Send a test notification
php artisan macos:check-updates [email protected]

Restart queue worker:
```
php artisan queue:restart
```

Check worker logs:

# Application logs
tail -f storage/logs/laravel.log

# Worker logs (if using supervisor)
tail -f storage/logs/worker.log

Logs

Check application logs for detailed error information:

tail -f storage/logs/laravel.log

🤝 Contributing

We welcome contributions from the MacAdmin community! Here's how you can help:

🐛 Bug Reports

Found a bug? Please open an issue with:

Clear description of the problem
Steps to reproduce the issue
Expected vs actual behavior
Environment details (PHP version, server type, etc.)

💡 Feature Requests

Have ideas for improvements? We'd love to hear them:

Smart Customization Options (Email templates?)
Email notification enhancements (Slack, Teams, SMS integration)
Advanced scheduling options (per-department deadlines)
Reporting features (compliance reports, analytics)
Integration capabilities (JAMF, Kandji, Munki, SimpleMDM)

🔧 Code Contributions

What We Need Most

Email Template Improvements: Better mobile responsiveness
MDM Integration: Sync the subscribed macOS versions with your MDM or inventory solution
IDP Integration: Connect with identity providers for smart updating of subscribers
Internationalization: Support for multiple languages
Advanced Analytics: Better reporting and insights
Testing: More test coverage for edge cases

Development Setup

# 1. Fork the repository
git clone https://github.com/wycomco/macos-update-notifier.git

# 2. Install development dependencies
composer install
npm install

# 3. Set up testing environment
cp .env.testing.example .env.testing
php artisan migrate --env=testing

# 4. Run tests
php artisan test

# 5. Start development server
npm run dev
php artisan serve

Coding Standards

Follow PSR-12 coding style
Write tests for new features
Update documentation for any changes
Use meaningful commit messages

📝 Documentation

User Guides: Help write installation instructions for different platforms
Video Tutorials: Create setup walkthroughs for non-developers
Translation: Help translate the interface to other languages

🆘 Support & Community

Getting Help

💬 MacAdmins Slack: Join #macos-update-notifier channel
📖 Documentation: Check our Wiki
🐛 GitHub Issues: Technical problems and bugs
📚 Laravel Docs: Framework documentation

🔒 Security & Privacy

Security Measures

🔐 Secure Authentication: Magic link system eliminates password vulnerabilities
🛡️ Data Protection: Minimal data collection, secure storage practices
🔍 Input Validation: All user inputs are sanitized and validated
📝 Audit Logs: Track administrative actions for compliance

Privacy Considerations

Data Collection: Only email addresses and update preferences
No Tracking: No user behavior analytics or tracking cookies
Self-Hosted: Full control over your subscriber data
GDPR Compliant: Built-in unsubscribe and data deletion features

Reporting Security Issues

Found a security vulnerability? Please email [email protected] directly rather than opening a public issue.

📄 License & Legal

This project is open source software licensed under the MIT License.

What This Means

✅ Commercial Use: Use in your organization freely
✅ Modification: Customize for your needs
✅ Distribution: Share with other MacAdmins
✅ Private Use: Use internally without restrictions

Attribution

While not required, we appreciate attribution when you share or modify this project.

🙏 Acknowledgments

Special thanks to:

MacAdmins Community: For inspiration and feedback
SOFA Project: For the macOS release data feed
Laravel Community: For the amazing framework
Beta Testers: MacAdmins who helped test and improve the system

Made with ❤️ for the MacAdmin community

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
app		app
bootstrap		bootstrap
config		config
database		database
public		public
resources		resources
routes		routes
storage		storage
tests		tests
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG		CHANGELOG
LICENSE.md		LICENSE.md
README.md		README.md
artisan		artisan
composer.json		composer.json
composer.lock		composer.lock
package-lock.json		package-lock.json
package.json		package.json
phpunit.xml		phpunit.xml
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
vite.config.js		vite.config.js

License

wycomco/macos-update-notifier

Folders and files

Latest commit

History

Repository files navigation