@khester/create-dynamics-app 1.0.8 → 1.1.0

package/templates/dynamics-365-starter/deployment/README.md

@@ -0,0 +1,484 @@
+# Deployment Automation Suite
+
+This directory contains comprehensive deployment automation tools for Dynamics 365 consulting
+projects.
+
+## Overview
+
+The deployment automation suite provides:
+
+- **Cross-platform deployment scripts** (PowerShell and Bash)
+- **Environment-specific configuration management**
+- **Automated backup and rollback capabilities**
+- **Web resource and solution deployment**
+- **Post-deployment testing and validation**
+- **Notification and reporting systems**
+
+## Directory Structure
+
+```
+deployment/
+├── scripts/
+│   ├── deploy.ps1              # PowerShell deployment script (Windows)
+│   ├── deploy.sh               # Bash deployment script (Linux/macOS)
+│   ├── rollback.ps1           # Rollback automation
+│   └── health-check.ps1       # Environment health monitoring
+├── templates/
+│   ├── solution-template.xml   # Solution deployment template
+│   └── web-resource-config.json # Web resource configuration
+├── logs/                       # Deployment logs (auto-created)
+├── backups/                   # Environment backups (auto-created)
+├── pipelines/
+│   ├── azure-pipelines.yml    # Azure DevOps pipeline
+│   ├── github-actions.yml     # GitHub Actions workflow
+│   └── jenkins.groovy         # Jenkins pipeline
+└── README.md                  # This file
+```
+
+## Quick Start
+
+### Prerequisites
+
+#### For PowerShell (Windows)
+
+```powershell
+# Install required PowerShell modules
+Install-Module -Name Microsoft.PowerApps.Administration.PowerShell
+Install-Module -Name Microsoft.PowerApps.PowerShell
+```
+
+#### For Bash (Linux/macOS)
+
+```bash
+# Install required tools
+brew install jq curl node npm  # macOS
+# or
+apt-get install jq curl nodejs npm  # Ubuntu/Debian
+```
+
+### Basic Deployment
+
+#### Windows (PowerShell)
+
+```powershell
+# Deploy to development
+.\deployment\scripts\deploy.ps1 -Environment dev
+
+# Deploy to production with backup
+.\deployment\scripts\deploy.ps1 -Environment prod
+
+# Dry run for testing
+.\deployment\scripts\deploy.ps1 -Environment prod -DryRun
+```
+
+#### Linux/macOS (Bash)
+
+```bash
+# Deploy to development
+./deployment/scripts/deploy.sh dev
+
+# Deploy to production with backup
+./deployment/scripts/deploy.sh prod
+
+# Dry run for testing
+./deployment/scripts/deploy.sh prod --dry-run
+```
+
+## Configuration
+
+### Environment Configuration
+
+Each environment requires a configuration file in `config/environments/`:
+
+```json
+{
+  "name": "Production",
+  "dynamics365": {
+    "orgUrl": "https://client.crm.dynamics.com",
+    "webApiUrl": "https://client.api.crm.dynamics.com/api/data/v9.2",
+    "tenantId": "your-tenant-id",
+    "environmentId": "your-environment-id"
+  },
+  "authentication": {
+    "type": "oauth2",
+    "clientId": "your-client-id",
+    "clientSecret": "your-client-secret"
+  },
+  "deployment": {
+    "strategy": "blue-green",
+    "rollbackEnabled": true,
+    "approvalRequired": true
+  },
+  "notifications": {
+    "deploymentSuccess": {
+      "enabled": true,
+      "channels": ["email", "teams"]
+    },
+    "deploymentFailure": {
+      "enabled": true,
+      "channels": ["email", "teams", "sms"]
+    }
+  }
+}
+```
+
+### Solution Configuration
+
+For solution-based deployments, place solution files in the `solutions/` directory:
+
+```
+solutions/
+├── 01-DynamicsUIKit_Base_1_0_0_0.zip
+├── 02-DynamicsUIKit_Components_1_0_0_0.zip
+└── 03-ClientCustomizations_1_0_0_0.zip
+```
+
+## Deployment Options
+
+### PowerShell Deployment Options
+
+```powershell
+# Basic deployment
+.\deploy.ps1 -Environment <env>
+
+# Advanced options
+.\deploy.ps1 -Environment <env> [OPTIONS]
+
+Options:
+  -Environment <string>     Target environment (dev, test, staging, prod)
+  -ConfigPath <string>      Configuration directory path
+  -DryRun                   Perform dry run without changes
+  -Force                    Force deployment even if errors occur
+  -SolutionPath <string>    Solution files directory
+  -SkipBackup               Skip environment backup
+  -Verbose                  Enable verbose output
+```
+
+### Bash Deployment Options
+
+```bash
+# Basic deployment
+./deploy.sh <environment>
+
+# Advanced options
+./deploy.sh [OPTIONS] <environment>
+
+Options:
+  -c, --config-path PATH    Configuration directory path
+  -s, --solution-path PATH  Solution files directory path
+  -n, --dry-run            Perform dry run without changes
+  -f, --force              Force deployment even if errors occur
+  --skip-backup            Skip environment backup
+  -v, --verbose            Enable verbose output
+  -h, --help               Show help message
+```
+
+## Deployment Process
+
+### 1. Pre-Deployment Phase
+
+- ✅ Load environment configuration
+- ✅ Validate prerequisites and dependencies
+- ✅ Check authentication and permissions
+- ✅ Create environment backup (optional)
+- ✅ Run pre-deployment tests
+
+### 2. Build Phase
+
+- ✅ Build application with `npm run build:prod`
+- ✅ Validate build artifacts
+- ✅ Prepare web resources for deployment
+- ✅ Package solutions (if applicable)
+
+### 3. Deployment Phase
+
+- ✅ Deploy web resources to Dynamics 365
+- ✅ Import and activate solutions
+- ✅ Publish all customizations
+- ✅ Configure security roles and permissions
+- ✅ Update system configurations
+
+### 4. Post-Deployment Phase
+
+- ✅ Run health checks and validation tests
+- ✅ Verify web resource accessibility
+- ✅ Test critical functionality
+- ✅ Send deployment notifications
+- ✅ Generate deployment report
+
+### 5. Monitoring Phase
+
+- ✅ Monitor system performance
+- ✅ Track user adoption metrics
+- ✅ Alert on any issues or errors
+- ✅ Schedule maintenance tasks
+
+## CI/CD Integration
+
+### Azure DevOps Pipeline
+
+```yaml
+# azure-pipelines.yml
+trigger:
+  branches:
+    include:
+      - main
+      - develop
+
+pool:
+  vmImage: 'windows-latest'
+
+stages:
+  - stage: Build
+    jobs:
+      - job: BuildJob
+        steps:
+          - task: NodeTool@0
+            inputs:
+              versionSpec: '18.x'
+          - script: npm ci
+          - script: npm run build:prod
+          - task: PublishBuildArtifacts@1
+
+  - stage: DeployDev
+    condition: eq(variables['Build.SourceBranch'], 'refs/heads/develop')
+    jobs:
+      - deployment: DeployToDev
+        environment: 'Dynamics365-Dev'
+        strategy:
+          runOnce:
+            deploy:
+              steps:
+                - task: PowerShell@2
+                  inputs:
+                    filePath: '$(Pipeline.Workspace)/drop/deployment/scripts/deploy.ps1'
+                    arguments: '-Environment dev'
+```
+
+### GitHub Actions Workflow
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy to Dynamics 365
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build:prod
+      - uses: actions/upload-artifact@v3
+        with:
+          name: build-artifacts
+          path: dist/
+
+  deploy-dev:
+    if: github.ref == 'refs/heads/develop'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: development
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/download-artifact@v3
+        with:
+          name: build-artifacts
+          path: dist/
+      - name: Deploy to Development
+        run: ./deployment/scripts/deploy.sh dev
+        env:
+          D365_CLIENT_ID: ${{ secrets.D365_DEV_CLIENT_ID }}
+          D365_CLIENT_SECRET: ${{ secrets.D365_DEV_CLIENT_SECRET }}
+```
+
+## Backup and Rollback
+
+### Automatic Backup
+
+The deployment scripts automatically create backups before deployment:
+
+```bash
+# Backups are stored in deployment/backups/
+backup-prod-20231201-143022.tar.gz
+backup-test-20231201-120045.tar.gz
+```
+
+### Manual Rollback
+
+```powershell
+# PowerShell rollback
+.\deployment\scripts\rollback.ps1 -Environment prod -BackupFile "backup-prod-20231201-143022.tar.gz"
+```
+
+```bash
+# Bash rollback
+./deployment/scripts/rollback.sh prod backup-prod-20231201-143022.tar.gz
+```
+
+## Monitoring and Health Checks
+
+### Automated Health Monitoring
+
+```powershell
+# Run health checks
+.\deployment\scripts\health-check.ps1 -Environment prod
+
+# Schedule regular health checks
+Register-ScheduledTask -TaskName "D365HealthCheck" -Trigger (New-ScheduledTaskTrigger -Daily -At 2am)
+```
+
+### Monitoring Endpoints
+
+The deployment includes health check endpoints:
+
+- `/api/health` - Basic health status
+- `/api/health/detailed` - Detailed system information
+- `/api/health/dependencies` - External dependency status
+
+## Troubleshooting
+
+### Common Issues
+
+#### Authentication Failures
+
+```bash
+# Check service principal permissions
+./deployment/scripts/test-auth.sh prod
+
+# Verify configuration
+./deployment/scripts/validate-config.sh prod
+```
+
+#### Web Resource Deployment Issues
+
+```powershell
+# Check file permissions and sizes
+.\deployment\scripts\validate-webresources.ps1
+
+# Test individual web resource deployment
+.\deployment\scripts\deploy-webresource.ps1 -Name "dynamics_ui_kit_index_js" -File "dist/index.js"
+```
+
+#### Solution Import Failures
+
+```bash
+# Validate solution file
+./deployment/scripts/validate-solution.sh solutions/MyApp_1_0_0_0.zip
+
+# Check dependencies
+./deployment/scripts/check-dependencies.sh prod
+```
+
+### Debug Mode
+
+Enable verbose logging for troubleshooting:
+
+```bash
+# Enable debug mode
+./deployment/scripts/deploy.sh prod --verbose
+
+# Check deployment logs
+tail -f deployment/logs/deploy-prod-*.log
+```
+
+### Log Analysis
+
+```bash
+# Search for errors in logs
+grep "ERROR" deployment/logs/deploy-prod-*.log
+
+# Check deployment timing
+grep "completed" deployment/logs/deploy-prod-*.log
+```
+
+## Security Best Practices
+
+### Secure Configuration Management
+
+1. **Never commit secrets** to version control
+2. **Use Azure Key Vault** for production secrets
+3. **Implement least privilege** access policies
+4. **Enable audit logging** for all operations
+5. **Use managed identities** where possible
+
+### Environment Isolation
+
+```json
+{
+  "security": {
+    "enableAuditLogging": true,
+    "requireMFA": true,
+    "sessionTimeout": 480,
+    "enableConditionalAccess": true,
+    "allowedIPs": ["203.0.113.0/24"],
+    "dataLossPreventionEnabled": true
+  }
+}
+```
+
+## Performance Optimization
+
+### Deployment Speed Optimization
+
+1. **Parallel web resource uploads**
+2. **Incremental solution deployments**
+3. **Delta-only updates**
+4. **Compressed file transfers**
+5. **Cached build artifacts**
+
+### Resource Optimization
+
+```json
+{
+  "performance": {
+    "enableCaching": true,
+    "cacheTimeout": 300,
+    "batchSize": 100,
+    "timeoutMs": 30000,
+    "retryAttempts": 3,
+    "enableCompression": true
+  }
+}
+```
+
+## Support and Maintenance
+
+### Regular Maintenance Tasks
+
+1. **Clean up old backups** (automated)
+2. **Monitor deployment metrics**
+3. **Update deployment scripts**
+4. **Review security configurations**
+5. **Test disaster recovery procedures**
+
+### Getting Help
+
+- **Documentation**: Check this README and inline script comments
+- **Logs**: Review deployment logs in `deployment/logs/`
+- **Support**: Contact the development team with log files
+- **Community**: Check GitHub issues and discussions
+
+## Contributing
+
+When contributing to the deployment automation:
+
+1. **Test thoroughly** in development environment
+2. **Follow naming conventions** for scripts and configurations
+3. **Document all parameters** and options
+4. **Include error handling** and validation
+5. **Update this README** with any changes
+
+---
+
+This deployment automation suite enables reliable, repeatable, and scalable deployments for Dynamics
+365 consulting projects across multiple clients and environments.