Add Dev Container for Codespaces (#44)

Author: simonkurtz-MSFT

.devcontainer/README.md

@@ -47,26 +47,69 @@ All packages from `requirements.txt` are pre-installed:
 ### Environment Configuration
 - **PYTHONPATH** - Automatically configured to include shared Python modules
 - **Jupyter Kernel** - Custom kernel named "APIM Samples Python"
-- **Azure CLI** - Configured for container-friendly authentication
+- **Azure CLI** - Installed and ready for authentication (requires tenant-specific `az login` inside container)
 - **Port Forwarding** - Common development ports (3000, 5000, 8000, 8080) pre-configured
 
 ## 🔧 Post-Setup Steps
 
-After the container starts, you'll need to:
+The dev container automatically handles most setup during initialization. During the first build, you'll be prompted to configure Azure CLI authentication.
 
-1. **Sign in to Azure**:
-   ```bash
-   az login
-   ```
+### Automated Interactive Setup (During First Build)
+When the container starts for the first time, the setup script will automatically:
+1. **Install all dependencies** (Python packages, Azure CLI extensions)
+2. **Configure Jupyter environment** with custom kernel
+3. **Prompt for Azure CLI configuration**:
+   - Mount local Azure config (preserves login between rebuilds)
+   - Use manual login (run tenant-specific `az login` each time)
+   - Configure manually later
+
+### Manual Configuration (If Needed Later)
+If you skipped the initial configuration or want to change it:
+
+**Interactive Setup**:
+```bash
+python .devcontainer/configure-azure-mount.py
+```
+
+**Manual Azure Login**:
+```bash
+# Log in to your specific tenant
+az login --tenant <your-tenant-id-or-domain>
 
-2. **Verify your Azure setup**:
-   Execute `shared/jupyter/verify-az-account.ipynb`
+# Set your target subscription
+az account set --subscription <your-subscription-id-or-name>
+
+# Verify your authentication context
+az account show
+```
 
+### Continue with Development
+After setup is complete:
+1. **Verify your Azure setup**: Execute `shared/jupyter/verify-az-account.ipynb`
+2. **Test your environment**: Run `python .devcontainer/verify-setup.py`
 3. **Start exploring**:
    - Navigate to any infrastructure folder (`infrastructure/`)
    - Run the `create.ipynb` notebook to set up infrastructure
    - Explore samples in the `samples/` directory
 
+## 🔧 Troubleshooting
+
+If you encounter import errors or module resolution issues, see:
+- [Import Troubleshooting Guide](.devcontainer/IMPORT-TROUBLESHOOTING.md)
+- [Setup Notes](.devcontainer/SETUP-NOTES.md)
+
+Common quick fixes:
+```bash
+# Fix Python path for local development
+python setup/setup_python_path.py --generate-env
+
+# Verify setup
+python .devcontainer/verify-setup.py
+
+# Rebuild dev container if needed
+Dev Containers: Rebuild Container
+```
+
 ## 🏗️ Architecture
 
 The dev container is built on:
@@ -77,10 +120,67 @@ The dev container is built on:
 
 ## 🔄 Azure CLI Authentication
 
-The container mounts your local `~/.azure` directory to preserve authentication state between container rebuilds. This means:
-- Your Azure login persists across sessions
-- Your Azure CLI configuration is maintained
-- No need to repeatedly authenticate
+### Quick Setup (Recommended)
+
+Run the interactive configuration script to automatically set up Azure CLI authentication for your platform:
+
+**Python (Cross-platform)**:
+```bash
+python .devcontainer/configure-azure-mount.py
+```
+
+**PowerShell (Windows)**:
+```powershell
+.\.devcontainer\configure-azure-mount.ps1
+```
+
+**Bash (Linux/macOS)**:
+```bash
+./.devcontainer/configure-azure-mount.sh
+```
+
+### Configuration Options
+
+The setup script provides three choices:
+
+**Option 1: Mount local Azure CLI config**
+- ✅ Preserves login between container rebuilds
+- ✅ Uses your existing tenant-specific `az login` from host machine
+- ✅ Works on Windows (`${localEnv:USERPROFILE}/.azure`) and Unix (`${localEnv:HOME}/.azure`)
+- ✅ Best for: Personal development with stable logins
+
+**Option 2: Use manual login inside container [RECOMMENDED]**
+- ✅ Run tenant-specific `az login` each time container starts
+- ✅ More secure, fresh authentication each session  
+- ✅ Works universally across all platforms and environments
+- ✅ Best for: Shared environments, GitHub Codespaces
+- ✅ Ensures you're working with the correct tenant and subscription
+
+**Option 3: Configure manually later**
+- ✅ No changes made to devcontainer.json
+- ✅ You can edit the configuration files yourself
+- ✅ Full control over mount configuration
+
+### Mount Preservation
+
+The configuration script intelligently preserves any existing mounts (like SSH keys, additional volumes) while only managing Azure CLI mounts. This ensures your custom development setup remains intact.
+
+### Non-Interactive Environments
+
+In environments like GitHub Codespaces automation, the script automatically detects non-interactive contexts and safely defaults to Option 2 (manual login) for maximum reliability.
+
+### Manual Options
+
+**Option 1: Mount Local Azure Config**
+- Preserves authentication between container rebuilds
+- Platform-specific (configured automatically by the setup script)
+
+**Option 2: Manual Login**
+- Log in to your specific tenant: `az login --tenant <your-tenant-id-or-domain>`
+- Set your target subscription: `az account set --subscription <your-subscription-id-or-name>`
+- Verify context: `az account show`
+- Works universally across all platforms
+- Requires re-authentication after container rebuilds
 
 ## 🐛 Troubleshooting
 
@@ -119,7 +219,7 @@ If you need to rebuild the container:
 
 ## 🔒 Security Considerations
 
-- Azure credentials are mounted from your local machine
+- Azure credentials are handled through tenant-specific `az login` inside the container (or optionally mounted)
 - The container runs as a non-root user (`vscode`)
 - All dependencies are installed from official sources
 - Network access is controlled through VS Code's port forwarding

.devcontainer/configure-azure-mount.ps1

@@ -0,0 +1,102 @@
+# Azure CLI Configuration Setup for APIM Samples Dev Container
+# This PowerShell script provides an alternative to the Python configuration script
+
+Write-Host "🚀 APIM Samples Dev Container Azure CLI Setup" -ForegroundColor Cyan
+Write-Host "==================================================" -ForegroundColor Cyan
+
+Write-Host "🔧 Azure CLI Configuration Setup" -ForegroundColor Yellow
+Write-Host "========================================" -ForegroundColor Yellow
+
+# Detect platform
+$platform = "Windows"
+Write-Host "Detected platform: $platform" -ForegroundColor Green
+
+Write-Host "`nHow would you like to handle Azure CLI authentication?" -ForegroundColor White
+Write-Host "1. Mount local Azure CLI config (preserves login between container rebuilds)" -ForegroundColor White
+Write-Host "2. Use manual tenant-specific login inside container (requires explicit tenant/subscription setup each time)" -ForegroundColor White
+Write-Host "3. Let me configure this manually later" -ForegroundColor White
+
+do {
+    $choice = Read-Host "`nEnter your choice (1-3)"
+} while ($choice -notin @("1", "2", "3"))
+
+# Path to devcontainer.json
+$devcontainerPath = Join-Path $PSScriptRoot "devcontainer.json"
+$backupPath = "$devcontainerPath.backup"
+
+if (-not (Test-Path $devcontainerPath)) {
+    Write-Host "❌ devcontainer.json not found at: $devcontainerPath" -ForegroundColor Red
+    exit 1
+}
+
+# Create backup
+try {
+    Copy-Item $devcontainerPath $backupPath -Force
+    Write-Host "✅ Backup created: $backupPath" -ForegroundColor Green
+} catch {
+    Write-Host "❌ Failed to create backup: $_" -ForegroundColor Red
+    exit 1
+}
+
+# Read and parse devcontainer.json (simple approach for PowerShell)
+try {
+    $content = Get-Content $devcontainerPath -Raw | ConvertFrom-Json -Depth 10
+    
+    # Remove existing mounts if present
+    if ($content.PSObject.Properties.Name -contains "mounts") {
+        $content.PSObject.Properties.Remove("mounts")
+    }
+    
+    switch ($choice) {
+        "1" {
+            # Add Windows mount configuration
+            $mount = @{
+                source = "`${localEnv:USERPROFILE}/.azure"
+                target = "/home/vscode/.azure"
+                type = "bind"
+            }
+            $content | Add-Member -MemberType NoteProperty -Name "mounts" -Value @($mount)
+            Write-Host "✅ Configured Azure CLI mounting for Windows" -ForegroundColor Green
+        }        "2" {
+            Write-Host "✅ Configured for manual Azure CLI login with tenant/subscription specification" -ForegroundColor Green
+            Write-Host "   You'll need to run tenant-specific login after container startup:" -ForegroundColor Yellow
+            Write-Host "   az login --tenant <your-tenant-id-or-domain>" -ForegroundColor Yellow
+            Write-Host "   az account set --subscription <your-subscription-id-or-name>" -ForegroundColor Yellow
+            Write-Host "   az account show  # Verify your context" -ForegroundColor Yellow
+        }
+        "3" {
+            Write-Host "✅ No automatic configuration applied" -ForegroundColor Green
+            Write-Host "   You can manually edit .devcontainer/devcontainer.json later" -ForegroundColor Yellow
+        }
+    }
+    
+    # Save the updated configuration
+    $content | ConvertTo-Json -Depth 10 | Set-Content $devcontainerPath -Encoding UTF8
+    Write-Host "✅ devcontainer.json updated successfully" -ForegroundColor Green
+    
+} catch {
+    Write-Host "❌ Failed to update devcontainer.json: $_" -ForegroundColor Red
+    exit 1
+}
+
+Write-Host "`n🎉 Configuration completed successfully!" -ForegroundColor Green
+
+switch ($choice) {
+    "1" {
+        Write-Host "`n📋 Next steps:" -ForegroundColor Cyan
+        Write-Host "1. Rebuild your dev container" -ForegroundColor White
+        Write-Host "2. Your local Azure CLI authentication will be available" -ForegroundColor White
+    }    "2" {
+        Write-Host "`n📋 Next steps:" -ForegroundColor Cyan
+        Write-Host "1. Start/rebuild your dev container" -ForegroundColor White
+        Write-Host "2. Sign in with tenant-specific authentication:" -ForegroundColor White
+        Write-Host "   az login --tenant <your-tenant-id-or-domain>" -ForegroundColor White
+        Write-Host "   az account set --subscription <your-subscription-id-or-name>" -ForegroundColor White
+        Write-Host "   az account show  # Verify your context" -ForegroundColor White
+    }
+    "3" {
+        Write-Host "`n📋 Next steps:" -ForegroundColor Cyan
+        Write-Host "1. Edit .devcontainer/devcontainer.json manually if needed" -ForegroundColor White
+        Write-Host "2. See the commented examples in the file" -ForegroundColor White
+    }
+}