@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/deployment/QUICKSTART-MAC.md

@@ -0,0 +1,507 @@
+# Quick Start Guide - Mac Developers
+
+🍎 **Platform-specific setup for Mac developers using Bash**
+
+## Prerequisites
+
+### Required Software
+
+- **macOS 10.15+** (Catalina or newer)
+- **Homebrew** package manager
+- **Node.js 18+** and **npm**
+- **Git**
+
+### Install Development Tools
+
+```bash
+# Install Homebrew (if not already installed)
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+# Install required tools
+brew install node npm git jq curl
+
+# Verify installations
+node --version
+npm --version
+git --version
+jq --version
+```
+
+### Optional: Install PowerShell Core (Alternative)
+
+```bash
+# If you prefer PowerShell (optional)
+brew install --cask powershell
+
+# Verify PowerShell installation
+pwsh --version
+```
+
+## Project Setup
+
+### 1. Clone and Setup Project
+
+```bash
+# Clone the project
+git clone https://github.com/your-org/your-dynamics-project.git
+cd your-dynamics-project
+
+# Install dependencies
+npm install
+
+# Build the project
+npm run build:prod
+```
+
+### 2. Configure Environment
+
+```bash
+# Copy environment template
+cp config/environments/template.json config/environments/dev.json
+
+# Edit configuration (use your preferred editor)
+code config/environments/dev.json  # VS Code
+# or
+nano config/environments/dev.json  # Terminal editor
+```
+
+### 3. Validate Setup
+
+```bash
+# Make deployment script executable
+chmod +x deployment/scripts/deploy.sh
+chmod +x deployment/scripts/validate-setup.sh
+chmod +x deployment/scripts/test-connection.sh
+
+# Run validation script
+./deployment/scripts/validate-setup.sh
+
+# Test connection to D365
+./deployment/scripts/test-connection.sh dev
+```
+
+## Daily Deployment Workflow
+
+### Development Deployment
+
+```bash
+# Quick development deployment
+./deployment/scripts/deploy.sh dev
+
+# With verbose output
+./deployment/scripts/deploy.sh dev --verbose
+
+# Dry run (test without changes)
+./deployment/scripts/deploy.sh dev --dry-run
+```
+
+### Production Deployment
+
+```bash
+# Production deployment with backup
+./deployment/scripts/deploy.sh prod
+
+# Force deployment (skip some validations)
+./deployment/scripts/deploy.sh prod --force
+
+# Skip backup (faster deployment)
+./deployment/scripts/deploy.sh prod --skip-backup
+```
+
+### Entity Generation
+
+```bash
+# Generate new entity
+npm run generate:entity -- --entity "salesorder" --display-name "Sales Order"
+
+# Generate multiple entities
+npm run generate:entity -- --entity "product" --display-name "Product"
+npm run generate:entity -- --entity "pricing" --display-name "Pricing Rule"
+```
+
+## Common Commands Reference
+
+### Build Commands
+
+```bash
+npm run build:dev       # Development build (unminified)
+npm run build:prod      # Production build (optimized)
+npm run build:d365      # Dynamics 365 optimized build
+npm run clean           # Clean build artifacts
+```
+
+### Quality Checks
+
+```bash
+npm run lint            # Check code style
+npm run lint:fix        # Fix code style issues
+npm run typecheck       # TypeScript validation
+npm run quality         # Run all quality checks
+npm run test            # Run unit tests
+```
+
+### Metadata Operations
+
+```bash
+npm run metadata:pull -- --environment dev --entities "account,contact"
+npm run metadata:generate
+npm run metadata:validate -- --environment dev
+npm run metadata:sync -- --environment dev --all
+```
+
+### Deployment Operations
+
+```bash
+# Deploy to specific environment
+./deployment/scripts/deploy.sh <environment>
+
+# Rollback deployment
+./deployment/scripts/rollback.sh <environment> backup-file.tar.gz
+
+# Health check
+./deployment/scripts/health-check.sh <environment>
+
+# Monitor deployment
+./deployment/scripts/monitor.sh <environment>
+```
+
+## Bash Configuration
+
+### Shell Profile Setup
+
+```bash
+# Determine your shell
+echo $SHELL
+
+# For Zsh (default on macOS Catalina+)
+echo '# Dynamics 365 Development Aliases' >> ~/.zshrc
+echo 'alias d365deploy="./deployment/scripts/deploy.sh"' >> ~/.zshrc
+echo 'alias d365health="./deployment/scripts/health-check.sh"' >> ~/.zshrc
+echo 'alias d365rollback="./deployment/scripts/rollback.sh"' >> ~/.zshrc
+echo 'alias d365cd="cd ~/Code/YourProject"' >> ~/.zshrc
+
+# For Bash
+echo '# Dynamics 365 Development Aliases' >> ~/.bash_profile
+echo 'alias d365deploy="./deployment/scripts/deploy.sh"' >> ~/.bash_profile
+echo 'alias d365health="./deployment/scripts/health-check.sh"' >> ~/.bash_profile
+echo 'alias d365rollback="./deployment/scripts/rollback.sh"' >> ~/.bash_profile
+echo 'alias d365cd="cd ~/Code/YourProject"' >> ~/.bash_profile
+
+# Reload profile
+source ~/.zshrc  # or ~/.bash_profile
+```
+
+### Environment Variables
+
+```bash
+# Set environment variables for session
+export D365_ENVIRONMENT="dev"
+export D365_CLIENT_ID="your-client-id"
+
+# Make permanent (add to ~/.zshrc or ~/.bash_profile)
+echo 'export D365_ENVIRONMENT="dev"' >> ~/.zshrc
+echo 'export D365_CLIENT_ID="your-client-id"' >> ~/.zshrc
+```
+
+## Mac-Specific Tips
+
+### File Permissions
+
+```bash
+# Make all deployment scripts executable
+find deployment/scripts -name "*.sh" -exec chmod +x {} \;
+
+# Check file permissions
+ls -la deployment/scripts/
+```
+
+### Path Handling
+
+```bash
+# Use forward slashes for paths (native to Unix/Mac)
+./deployment/scripts/deploy.sh
+
+# Current directory reference
+./deployment/scripts/deploy.sh dev
+```
+
+### Using Finder Integration
+
+```bash
+# Open current directory in Finder
+open .
+
+# Open project in VS Code
+code .
+
+# Open specific file
+open config/environments/dev.json
+```
+
+### Terminal Configuration
+
+#### iTerm2 Setup (Recommended)
+
+```bash
+# Install iTerm2
+brew install --cask iterm2
+
+# Create D365 project profile in iTerm2:
+# 1. Open iTerm2 Preferences
+# 2. Go to Profiles
+# 3. Create new profile "D365 Development"
+# 4. Set working directory to your project folder
+# 5. Set custom color scheme if desired
+```
+
+#### Terminal.app Setup
+
+```bash
+# Create custom terminal profile:
+# 1. Open Terminal.app
+# 2. Go to Terminal > Preferences > Profiles
+# 3. Duplicate "Basic" profile
+# 4. Name it "D365 Development"
+# 5. Set startup directory to your project
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Permission Denied Errors
+
+```bash
+# Fix script permissions
+chmod +x deployment/scripts/deploy.sh
+
+# Check script permissions
+ls -la deployment/scripts/deploy.sh
+```
+
+#### Command Not Found
+
+```bash
+# Check if tool is installed
+which jq
+which curl
+which node
+
+# Install missing tools
+brew install jq curl node
+```
+
+#### Authentication Issues
+
+```bash
+# Clear any cached credentials
+rm -rf ~/.azure
+rm -rf ~/.config/powershell
+
+# Test authentication
+./deployment/scripts/test-auth.sh dev
+```
+
+#### Build Failures
+
+```bash
+# Clear npm cache
+npm cache clean --force
+
+# Remove node_modules and reinstall
+rm -rf node_modules
+npm install
+
+# Clear build artifacts
+npm run clean
+```
+
+#### Network Issues
+
+```bash
+# Check internet connectivity
+ping google.com
+
+# Test D365 connectivity
+curl -I https://yourdomain.crm.dynamics.com
+
+# Check for proxy issues
+echo $HTTP_PROXY
+echo $HTTPS_PROXY
+```
+
+### Performance Optimization
+
+```bash
+# Increase Node.js memory limit
+export NODE_OPTIONS="--max-old-space-size=4096"
+
+# Use faster package manager (optional)
+brew install pnpm
+# Then use 'pnpm install' instead of 'npm install'
+```
+
+## VS Code Integration
+
+### Recommended Extensions
+
+- **TypeScript** - Enhanced TypeScript support
+- **Bash IDE** - Bash script development
+- **REST Client** - Test D365 APIs
+- **GitLens** - Enhanced Git capabilities
+
+### Launch Configuration
+
+```json
+// .vscode/launch.json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Deploy to Dev",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/deployment/scripts/deploy.sh",
+      "args": ["dev", "--verbose"],
+      "cwd": "${workspaceFolder}",
+      "console": "integratedTerminal"
+    }
+  ]
+}
+```
+
+### Tasks Configuration
+
+```json
+// .vscode/tasks.json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Deploy to Dev",
+      "type": "shell",
+      "command": "./deployment/scripts/deploy.sh",
+      "args": ["dev"],
+      "group": "build",
+      "presentation": {
+        "echo": true,
+        "reveal": "always",
+        "focus": false,
+        "panel": "shared"
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Generate Entity",
+      "type": "shell",
+      "command": "npm",
+      "args": [
+        "run",
+        "generate:entity",
+        "--",
+        "--entity",
+        "${input:entityName}",
+        "--display-name",
+        "${input:displayName}"
+      ],
+      "group": "build"
+    }
+  ],
+  "inputs": [
+    {
+      "id": "entityName",
+      "description": "Entity logical name",
+      "default": "customentity",
+      "type": "promptString"
+    },
+    {
+      "id": "displayName",
+      "description": "Entity display name",
+      "default": "Custom Entity",
+      "type": "promptString"
+    }
+  ]
+}
+```
+
+## Docker Alternative (Optional)
+
+### Using Docker for Consistency
+
+```bash
+# Create Dockerfile for D365 development
+cat > Dockerfile << 'EOF'
+FROM node:18-alpine
+RUN apk add --no-cache bash jq curl git
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build:prod
+CMD ["./deployment/scripts/deploy.sh"]
+EOF
+
+# Build Docker image
+docker build -t d365-deploy .
+
+# Run deployment in container
+docker run --rm -v $(pwd)/config:/app/config d365-deploy dev
+```
+
+## Team Collaboration
+
+### Shared Scripts Compatibility
+
+All Bash scripts in `deployment/scripts/` work identically across all Mac machines and are
+compatible with Linux CI/CD systems.
+
+### Configuration Sharing
+
+- Environment configs in `config/environments/` are shared across team
+- Personal settings go in `.env.local` (not committed to git)
+- Use the same JSON configuration files as Windows team members
+
+### Log Files
+
+```bash
+# Deployment logs location
+ls -la deployment/logs/
+
+# View latest deployment log
+tail -f deployment/logs/deploy-dev-*.log
+
+# Search for errors
+grep -i error deployment/logs/deploy-dev-*.log
+```
+
+## Compatibility with Windows Team Members
+
+### Same Functionality
+
+✅ **Identical deployment results** as Windows PowerShell scripts  
+✅ **Same configuration files** work for both platforms  
+✅ **Same entity generation** and build processes  
+✅ **Compatible log formats** for shared troubleshooting
+
+### Command Equivalents
+
+| Windows PowerShell                       | Mac Bash                     | Result            |
+| ---------------------------------------- | ---------------------------- | ----------------- |
+| `.\deploy.ps1 -Environment dev`          | `./deploy.sh dev`            | Same deployment   |
+| `.\deploy.ps1 -Environment prod -DryRun` | `./deploy.sh prod --dry-run` | Same dry run      |
+| `.\health-check.ps1 -Environment prod`   | `./health-check.sh prod`     | Same health check |
+
+## Next Steps
+
+1. ✅ **Complete environment setup** using this guide
+2. ✅ **Run first deployment** to development environment
+3. ✅ **Generate your first entity** using the entity generator
+4. ✅ **Deploy to test environment** when ready
+5. ✅ **Set up CI/CD pipeline** for automated deployments
+
+For Windows team members, refer to `QUICKSTART-WINDOWS.md` for their platform-specific setup.
+
+---
+
+💡 **Tip**: Save this guide to your bookmarks and use the **Common Commands Reference** section for
+daily workflows!