Table of Contents

Setup and Configuration

This section provides detailed instructions for setting up the complete Documentation as Code infrastructure using Azure DevOps, DocFX, and Azure App Service.

Prerequisites

Before beginning the setup process, ensure you have:

Required Access and Permissions

  • Azure Subscription with Contributor or Owner permissions
  • Azure DevOps Organization with Project Administrator access
  • Domain Management access (if using custom domains)
  • Development Environment with administrative privileges

Required Software

  • Git (version 2.20 or later)
  • Node.js (version 16 or later)
  • DocFX (latest stable version)
  • Azure CLI (latest version)
  • PowerShell (version 7 or later)

Knowledge Requirements

  • Basic understanding of Git workflows
  • Familiarity with Azure services
  • Markdown writing proficiency
  • YAML configuration basics

Setup Sequence

Follow these steps in order for a successful implementation:

  1. Azure DevOps Repository Setup - Configure source control and collaboration
  2. DocFX Project Configuration - Set up static site generation
  3. Azure App Service Creation - Configure web hosting
  4. CI/CD Pipeline Setup - Implement automated deployment

Environment Planning

Development Environment

Local Development Setup:

  • Individual developer workstations
  • DocFX installation and configuration
  • Git repository cloning
  • Local build and preview capabilities

Collaboration Tools:

  • Visual Studio Code with extensions
  • Git GUI tools (optional)
  • Markdown editors and preview tools
  • Azure DevOps browser access

Cloud Infrastructure

Resource Naming Convention:

{project}-{environment}-{service}-{region}
├── docs-dev-app-eastus          # Development App Service
├── docs-prod-app-eastus         # Production App Service
├── docs-shared-rg-eastus        # Shared Resource Group
└── docs-devops-proj             # Azure DevOps Project

Resource Organization:

  • Resource Groups: Separate development and production
  • App Service Plans: Appropriate sizing for each environment
  • Application Insights: Monitoring and analytics
  • Key Vault: Secure configuration storage

Security Considerations

Access Control

Azure DevOps Security:

  • Branch protection policies
  • Pull request requirements
  • Code review assignments
  • Service connection security

Azure App Service Security:

  • Managed identity configuration
  • Network access restrictions
  • SSL certificate management
  • Security headers configuration

Secrets Management

Sensitive Information Handling:

  • Azure Key Vault integration
  • Environment variable security
  • Connection string protection
  • API key management

Network Configuration

Domain and DNS

Custom Domain Setup:

  • Domain registration or delegation
  • DNS zone configuration
  • SSL certificate acquisition
  • CDN integration (optional)

Network Security:

  • Application Gateway configuration
  • Firewall rules
  • DDoS protection
  • Geographic restrictions

Monitoring and Alerting

Application Insights

Telemetry Configuration:

  • Page view tracking
  • User behavior analytics
  • Performance monitoring
  • Error tracking and alerting

Custom Metrics:

  • Documentation usage patterns
  • Search query analytics
  • Content effectiveness metrics
  • User engagement tracking

Backup and Recovery

Data Protection

Repository Backup:

  • Azure DevOps backup policies
  • Git repository mirroring
  • Content export procedures
  • Version history preservation

Application Recovery:

  • App Service backup configuration
  • Database backup (if applicable)
  • Configuration backup
  • Disaster recovery procedures

Performance Optimization

Initial Configuration

App Service Performance:

  • Appropriate service plan selection
  • Auto-scaling configuration
  • Application settings optimization
  • Connection pooling setup

Content Delivery:

  • CDN integration planning
  • Static asset optimization
  • Caching strategy implementation
  • Compression configuration

Validation Checklist

Before proceeding to the next phase, verify:

Infrastructure Validation

  • [ ] Azure DevOps repository created and accessible
  • [ ] DocFX project builds successfully locally
  • [ ] Azure App Service deploys and serves content
  • [ ] CI/CD pipeline runs without errors
  • [ ] Custom domain resolves correctly (if applicable)
  • [ ] SSL certificates are valid and configured
  • [ ] Monitoring and alerting are functional

Access Validation

  • [ ] Team members can access Azure DevOps
  • [ ] Pull request workflows function correctly
  • [ ] Deployment permissions are properly configured
  • [ ] Service connections are authenticated
  • [ ] Key Vault access is working

Security Validation

  • [ ] Branch protection policies are enforced
  • [ ] Secrets are stored securely
  • [ ] Network access is properly restricted
  • [ ] Security headers are configured
  • [ ] Authentication is working correctly

Troubleshooting Common Issues

Setup Problems

Azure DevOps Issues:

  • Permission denied errors
  • Service connection failures
  • Repository access problems
  • Pipeline execution failures

DocFX Build Issues:

  • NuGet package restoration failures
  • Template compilation errors
  • Markdown parsing problems
  • Asset reference issues

Azure App Service Issues:

  • Deployment failures
  • Runtime errors
  • Configuration problems
  • Performance issues

Resolution Strategies

Diagnostic Tools:

  • Azure DevOps build logs
  • App Service diagnostic tools
  • Application Insights telemetry
  • Browser developer tools

Common Solutions:

  • Clear caches and restart services
  • Verify configuration settings
  • Check permission assignments
  • Review log files for errors

Next Steps

Once setup is complete:

  1. Content Strategy Planning - Organize your documentation approach
  2. Development Workflow Setup - Establish daily processes
  3. Team Training - Educate team members
  4. Content Migration - Move existing documentation

Additional Resources

This setup guide ensures a robust foundation for your Documentation as Code implementation. Each step includes validation checkpoints to verify successful configuration.

Edit this page