@khester/create-dynamics-app 1.1.0 → 2.1.0

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

@@ -1,507 +0,0 @@
-# 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!