Mac Dock Integration for One-Click Startup

Overview

This guide enables you to add Piper Morgan to your Mac dock for one-click startup, making your daily 6:00 AM PT standup routine seamless and frictionless.

🎯 Benefits

πŸ“‹ Prerequisites

System Requirements

Piper Morgan Setup

πŸš€ Setup Instructions

Step 1: Create Startup Script

First, create the startup script in your Piper Morgan directory:

# Navigate to your Piper Morgan directory
cd /path/to/piper-morgan

# Create the startup script
cat > start-piper.sh << 'EOF'
#!/bin/bash

# Piper Morgan One-Click Startup Script
# Version: 1.0.0
# Purpose: Launch Piper Morgan with health checks

set -e  # Exit on any error

echo "πŸš€ Starting Piper Morgan..."
echo "================================"

# Check if Docker Desktop is running
if ! docker info > /dev/null 2>&1; then
    echo "❌ Docker Desktop is not running"
    echo "Please start Docker Desktop and try again"
    echo "You can find Docker Desktop in your Applications folder"
    exit 1
fi

echo "βœ… Docker Desktop is running"

# Check if we're in the right directory
if [ ! -f "main.py" ] || [ ! -f "web/app.py" ]; then
    echo "❌ Not in Piper Morgan directory"
    echo "Please navigate to your piper-morgan directory and try again"
    exit 1
fi

echo "βœ… Piper Morgan directory confirmed"

# Activate virtual environment
if [ -d "venv" ]; then
    echo "πŸ”§ Activating virtual environment..."
    source venv/bin/activate
    echo "βœ… Virtual environment activated"
else
    echo "❌ Virtual environment not found"
    echo "Please run: python -m venv venv && source venv/bin/activate"
    exit 1
fi

# Check Python dependencies
echo "πŸ” Checking Python dependencies..."
if ! python -c "import services" > /dev/null 2>&1; then
    echo "❌ Python dependencies not installed"
    echo "Please run: pip install -r requirements.txt"
    exit 1
fi

echo "βœ… Python dependencies verified"

# Start backend services
echo "πŸš€ Starting backend services..."
echo "Starting main.py in background..."
nohup python main.py > logs/backend.log 2>&1 &
BACKEND_PID=$!
echo "Backend PID: $BACKEND_PID"

# Wait for backend to start
echo "⏳ Waiting for backend to start..."
sleep 5

# Check backend health
if curl -s http://localhost:8001/health > /dev/null 2>&1; then
    echo "βœ… Backend is healthy"
else
    echo "❌ Backend health check failed"
    echo "Check logs/backend.log for details"
    exit 1
fi

# Start frontend
echo "🌐 Starting frontend..."
echo "Starting web/app.py..."
nohup python web/app.py > logs/frontend.log 2>&1 &
FRONTEND_PID=$!
echo "Frontend PID: $FRONTEND_PID"

# Wait for frontend to start
echo "⏳ Waiting for frontend to start..."
sleep 3

# Check frontend health
if curl -s http://localhost:8081/health > /dev/null 2>&1; then
    echo "βœ… Frontend is healthy"
else
    echo "❌ Frontend health check failed"
    echo "Check logs/frontend.log for details"
    exit 1
fi

# Create PID file for management
echo "$BACKEND_PID" > .piper-backend.pid
echo "$FRONTEND_PID" > .piper-frontend.pid

echo "πŸŽ‰ Piper Morgan is ready!"
echo "================================"
echo "🌐 Frontend: http://localhost:8081/"
echo "πŸ”§ Backend: http://localhost:8001/"
echo "πŸ“Š Health: http://localhost:8081/health"
echo ""
echo "πŸ’‘ Tip: Bookmark http://localhost:8081/ for quick access"
echo "πŸ”„ To stop: ./stop-piper.sh"
echo ""
echo "πŸš€ Ready for your 6:00 AM PT standup!"

# Open browser
open http://localhost:8081/
EOF

# Make the script executable
chmod +x start-piper.sh

Step 2: Create Stop Script

Create a companion stop script for clean shutdown:

# Create the stop script
cat > stop-piper.sh << 'EOF'
#!/bin/bash

# Piper Morgan Stop Script
# Version: 1.0.0
# Purpose: Clean shutdown of Piper Morgan services

echo "πŸ›‘ Stopping Piper Morgan..."
echo "================================"

# Stop backend
if [ -f ".piper-backend.pid" ]; then
    BACKEND_PID=$(cat .piper-backend.pid)
    if kill -0 $BACKEND_PID 2>/dev/null; then
        echo "πŸ›‘ Stopping backend (PID: $BACKEND_PID)..."
        kill $BACKEND_PID
        echo "βœ… Backend stopped"
    else
        echo "ℹ️  Backend already stopped"
    fi
    rm -f .piper-backend.pid
else
    echo "ℹ️  No backend PID file found"
fi

# Stop frontend
if [ -f ".piper-frontend.pid" ]; then
    FRONTEND_PID=$(cat .piper-frontend.pid)
    if kill -0 $FRONTEND_PID 2>/dev/null; then
        echo "πŸ›‘ Stopping frontend (PID: $FRONTEND_PID)..."
        kill $FRONTEND_PID
        echo "βœ… Frontend stopped"
    else
        echo "ℹ️  Frontend already stopped"
    fi
    rm -f .piper-frontend.pid
else
    echo "ℹ️  No frontend PID file found"
fi

# Clean up any remaining processes
echo "🧹 Cleaning up..."
pkill -f "python main.py" 2>/dev/null || true
pkill -f "python web/app.py" 2>/dev/null || true

echo "βœ… Piper Morgan stopped successfully"
echo "================================"
EOF

# Make the stop script executable
chmod +x stop-piper.sh

Step 3: Create Logs Directory

# Create logs directory
mkdir -p logs
echo "βœ… Logs directory created"

Step 4: Add to Mac Dock

  1. Open Finder and navigate to your Piper Morgan directory
  2. Drag the start-piper.sh file to your Mac dock
  3. Right-click the dock icon and select β€œOptions” β†’ β€œKeep in Dock”
  4. Customize the icon (optional - see Customization section below)

Option B: Create Application Bundle

For a more professional appearance, create an application bundle:

# Create application bundle
mkdir -p "Piper Morgan.app/Contents/MacOS"
mkdir -p "Piper Morgan.app/Contents/Resources"

# Copy startup script to bundle
cp start-piper.sh "Piper Morgan.app/Contents/MacOS/Piper Morgan"

# Make executable
chmod +x "Piper Morgan.app/Contents/MacOS/Piper Morgan"

# Create Info.plist
cat > "Piper Morgan.app/Contents/Info.plist" << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CFBundleExecutable</key>
    <string>Piper Morgan</string>
    <key>CFBundleIdentifier</key>
    <string>com.piper-morgan.startup</string>
    <key>CFBundleName</key>
    <string>Piper Morgan</string>
    <key>CFBundleVersion</key>
    <string>1.0.0</string>
    <key>CFBundleShortVersionString</key>
    <string>1.0.0</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleSignature</key>
    <string>????</string>
    <key>LSMinimumSystemVersion</key>
    <string>10.15</string>
</dict>
</plist>
EOF

echo "βœ… Application bundle created"

Step 5: Test the Integration

# Test the startup script
./start-piper.sh

# Verify services are running
curl http://localhost:8081/health
curl http://localhost:8001/health

# Test the stop script
./stop-piper.sh

🎨 Customization

Custom Dock Icon

  1. Create or download a 512x512 PNG icon
  2. Convert to ICNS format using Icon Composer or online tools
  3. Replace the icon in your application bundle:
# For application bundle
cp your-icon.icns "Piper Morgan.app/Contents/Resources/AppIcon.icns"

# Update Info.plist to reference the icon
# Add this to Info.plist:
# <key>CFBundleIconFile</key>
# <string>AppIcon.icns</string>

Dock Badge

The dock icon can show a badge indicating system status:

πŸ”§ Troubleshooting

Common Issues

Docker Desktop Not Running

# Error: Docker Desktop is not running
# Solution: Start Docker Desktop from Applications folder
open -a Docker

Port Already in Use

# Error: Port 8081 or 8000 already in use
# Solution: Stop existing services
./stop-piper.sh
# Or find and kill processes using the ports
lsof -ti:8081 | xargs kill -9
lsof -ti:8000 | xargs kill -9

Virtual Environment Issues

# Error: Virtual environment not found
# Solution: Recreate virtual environment
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Permission Denied

# Error: Permission denied on startup script
# Solution: Make script executable
chmod +x start-piper.sh
chmod +x stop-piper.sh

Log Analysis

Check logs for detailed error information:

# Backend logs
tail -f logs/backend.log

# Frontend logs
tail -f logs/frontend.log

# System logs
tail -f /var/log/system.log | grep -i piper

Health Check Commands

# Check service status
curl http://localhost:8081/health
curl http://localhost:8001/health

# Check process status
ps aux | grep -E "(main.py|app.py)"

# Check port usage
lsof -i :8081
lsof -i :8001

πŸ“± Daily Usage

Morning Standup (6:00 AM PT)

  1. Click the Piper Morgan dock icon
  2. Wait for startup completion (usually 30 seconds)
  3. Open browser to http://localhost:8081/
  4. Begin your daily standup routine

Evening Shutdown

  1. Click the stop script or run ./stop-piper.sh
  2. Verify services stopped (no processes running)
  3. Close browser tabs if desired

Quick Restart

# Quick restart for development
./stop-piper.sh && sleep 2 && ./start-piper.sh

πŸ”„ Maintenance

Regular Updates

# Update Piper Morgan
git pull origin main

# Update dependencies
source venv/bin/activate
pip install -r requirements.txt

# Test startup
./stop-piper.sh
./start-piper.sh

Log Rotation

# Rotate logs weekly
find logs/ -name "*.log" -mtime +7 -delete

Health Monitoring

# Check system health
./start-piper.sh --health-check-only

# Monitor resource usage
top -pid $(cat .piper-backend.pid) -pid $(cat .piper-frontend.pid)

πŸ“Š Performance Metrics

Startup Times

Resource Usage

🎯 Best Practices

Daily Routine

  1. Start Docker Desktop before 6:00 AM PT
  2. Click dock icon for one-click startup
  3. Verify health status before beginning standup
  4. Use stop script for clean shutdown

Development Workflow

  1. Keep startup script updated with latest changes
  2. Test startup/stop after major updates
  3. Monitor logs for any issues
  4. Update dependencies regularly

Troubleshooting Workflow

  1. Check Docker Desktop status first
  2. Verify virtual environment is activated
  3. Check logs for specific error messages
  4. Use health check commands for diagnosis
  5. Restart services if needed

πŸ“ž Support

GitHub Issues

Documentation


Status: βœ… Ready for Production Use Last Updated: September 10, 2025 Version: 2.0.0 - Enhanced for Issue #163 startup process changes Next Review: September 17, 2025

πŸ†• What’s New in Version 2.0.0 (September 2025)

Updated for Issue #163 Fixes

Enhanced Features