Skip to main content

Development Environment Setup

Development Environment Setup​

This guide provides comprehensive instructions for setting up a consistent development environment for the AI on Edge Flagship Accelerator. The recommended approach uses Visual Studio Code with Dev Containers to ensure all contributors work with the same tools and configurations.

Prerequisites​

Before setting up your development environment, ensure you have:

  • Docker Desktop installed and running
  • Visual Studio Code with the Dev Containers extension
  • Git configured with your credentials
  • GitHub account with appropriate repository access

Dev Container Setup​

The Dev Container provides a pre-configured development environment with all necessary tools, dependencies, and configurations.

Initial Setup​

  1. Clone the repository:

    git clone {{CLONE_URL}}
    cd edge-ai

  2. Open in Visual Studio Code:

    code .

  3. Reopen in Dev Container:

    • When prompted by VS Code, click "Reopen in Container"
    • Or use Command Palette: Remote-Containers: Reopen in Container
    • Wait for the container to build and start (first time may take several minutes)

  4. Verify installation:

    # Check that required tools are available
    terraform version
    az version
    kubectl version --client
    npm --version
    python3 --version

Git Configuration​

The Dev Container should copy your Git configuration from your host machine, but you may need to configure it manually:

# Set your Git identity
git config --global user.name "Your Name"
git config --global user.email "your.email@address"

# Verify configuration
git config --list

SSH Configuration​

For SSH to work with your local SSH keys in the Dev Container, configure an SSH agent following VS Code's instructions.

Important for Windows users: If you're running Windows and launch VS Code from the start menu or PowerShell, use the Windows SSH agent instructions (even if using WSL/WSL2).

Project Configuration​

npm Scripts​

The project uses package.json to define development scripts that provide consistent command execution across environments:

# Install project dependencies
npm install

# Development and testing commands
npm run lint                    # Run all linters
npm run lint-fix               # Fix common linting issues
npm run lint-devcontainer      # Run linters in Dev Container mode
npm run lint-fix-devcontainer  # Fix linting issues in Dev Container mode

# Markdown-specific commands
npm run mdlint                 # Run markdown linting
npm run mdlint-fix             # Fix markdown linting issues

# Spell checking
npm run cspell                 # Run spell checker

# Security scanning
npm run checkov-changes        # Scan changed folders only
npm run checkov-all           # Scan all folders

# Link validation
npm run link-check            # Check for language-specific links
npm run link-fix              # Fix language-specific links

Development Tools​

Linting and Code Quality​

The Dev Container includes pre-configured linting tools for maintaining code quality:

Linting​

Run linting tools locally:

# Run Terraform linting and formatting
npm run tflint-fix-all

# Run markdown linting
npm run mdlint-fix

For detailed information about the CI/CD lint jobs, see the Azure Pipelines lint templates documentation.

Markdown Linting​

Ensure documentation meets quality standards:

# Check markdown files
npm run mdlint

# Auto-fix markdown issues
npm run mdlint-fix

Note: Not all markdown errors are automatically fixable. Review and fix remaining issues manually.

Spell Checking​

Maintain professional documentation standards:

# Run spell checker
npm run cspell

If cspell detects unknown words that should be ignored:

Security Scanning​

The project integrates Checkov for infrastructure-as-code security analysis:

# Scan only changed folders
npm run checkov-changes

# Scan entire repository
npm run checkov-all

The scanning process:

  1. Detects folders with changes (or scans all with the all flag)
  2. Runs Checkov security scanner on identified folders
  3. Generates a JUnit XML report at ./checkov-results/code-analysis.xml

Infrastructure as Code Tools​

Terraform​

The Dev Container includes:

  • Terraform CLI for infrastructure provisioning
  • TFLint for Terraform code analysis
  • terraform-docs for automatic documentation generation
# Verify Terraform setup
terraform version

# Initialize a Terraform directory
terraform init

# Plan infrastructure changes
terraform plan

# Apply infrastructure changes
terraform apply

Bicep​

The Dev Container includes:

  • Bicep CLI for Azure Resource Manager template development
  • Bicep linter for code quality validation
# Verify Bicep setup
az bicep version

# Build Bicep files
az bicep build --file main.bicep

# Validate Bicep templates
az bicep validate --file main.bicep

Azure CLI​

Pre-configured for Azure resource management:

# Verify Azure CLI
az version

# Login to Azure (interactive)
az login

# Set subscription
az account set --subscription "your-subscription-id"

Kubernetes Tools​

The Dev Container includes kubectl and Helm for Kubernetes management:

# Verify kubectl
kubectl version --client

# Verify Helm
helm version

# Connect to a cluster
kubectl config use-context your-cluster-context

Development Workflow​

Branch Management​

  1. Create feature branches from the main branch:

    git checkout main
    git pull origin main
    git checkout -b feat/your-feature-name

  2. Make changes using the development tools and scripts

  3. Test changes using the provided npm scripts

  4. Commit changes following conventional commit guidelines

  5. Push and create pull requests using the PR guidelines

Code Quality Workflow​

Before committing changes:

# Run comprehensive linting
npm run lint-devcontainer

# Fix automatically fixable issues
npm run lint-fix-devcontainer

# Run security scanning on changes
npm run checkov-changes

# Verify spell checking
npm run cspell

Testing Workflow​

For infrastructure components:

# Navigate to component directory
cd src/000-cloud/010-security-identity/terraform

# Initialize and validate
terraform init
terraform validate
terraform plan

# Run component tests
cd ../tests
go test -v

GitHub Copilot Integration​

The development environment is optimized for GitHub Copilot assistance:

Custom Instructions​

The project includes comprehensive GitHub Copilot instructions that:

  • Automatically apply project conventions
  • Provide context-aware prompt file discovery
  • Ensure consistent code formatting and structure

Reusable Prompts​

Access specialized prompts via the Command Palette or chat:

  • Pull Request Generation: /pull-request - Generate comprehensive PR descriptions
  • Task Planning: /task-planner - Create structured implementation plans
  • Task Implementation: /task-implementer - Execute plans with progress tracking

For detailed information, see the AI-Assisted Engineering guide.

Troubleshooting​

Common Issues​

Container Build Failures​

If the Dev Container fails to build:

  1. Ensure Docker Desktop is running
  2. Check available disk space (containers require significant space)
  3. Try rebuilding: Command Palette → Remote-Containers: Rebuild Container

Git Authentication Issues​

If Git operations fail:

  1. Verify SSH agent configuration
  2. Check SSH key access to GitHub
  3. Use HTTPS with personal access tokens if SSH fails

Tool Version Mismatches​

If tools report unexpected versions:

  1. Rebuild the Dev Container to get latest tool versions
  2. Check .devcontainer/devcontainer.json for version specifications
  3. Update the container configuration if needed

Getting Help​

For development environment issues:

  1. Check the troubleshooting documentation
  2. Review existing GitHub issues
  3. Create a new issue with detailed environment information

Maintenance​

Container Updates​

Periodically update the Dev Container:

# Rebuild container with latest updates
# Command Palette → Remote-Containers: Rebuild Container

Dependency Updates​

Keep project dependencies current:

# Update npm dependencies
npm update

# Update container base images (requires container rebuild)

Alternative Setup (Manual)​

If you cannot use Dev Containers, manually install these tools:

  • Terraform >= 1.0
  • Azure CLI >= 2.0
  • Bicep CLI (via Azure CLI)
  • kubectl >= 1.20
  • Helm >= 3.0
  • Node.js >= 16 (for npm scripts)
  • Python >= 3.8
  • Docker (for container operations)

Note: Manual setup may result in tool version differences and inconsistent behavior. The Dev Container approach is strongly recommended for contributors.

Next Steps​

With your development environment configured:

  1. Review the Contributing Guidelines
  2. Understand the Coding Conventions
  3. Explore AI-Assisted Engineering workflows
  4. Choose a Getting Started guide based on your role

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.