Deployment Guide¶

This guide explains how to deploy FinOps Optimizer documentation to GitHub Pages with versioning support.

Overview¶

The documentation is automatically deployed to GitHub Pages whenever: - Code is pushed to the main branch - A new release is created - A pull request is opened (preview deployment)

Deployment Process¶

1. Automatic Deployment¶

The deployment is handled by GitHub Actions workflows:

Documentation Deployment: .github/workflows/docs.yml
Automatic Versioning: Integrated with GitHub releases

2. Manual Deployment¶

To deploy manually:

# Install dependencies
pip install mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-minify-plugin

# Build documentation
mkdocs build --clean

# Create version selector
python scripts/create_version_selector.py

# Deploy to GitHub Pages (requires GitHub CLI)
gh pages deploy site --branch gh-pages

Versioning¶

How Versioning Works¶

Main Branch: Always deploys to https://manikantesh.github.io/finopsoptimizer/
Releases: Deploy to https://manikantesh.github.io/finopsoptimizer/v2.0.0/
Version Selector: Allows users to switch between versions

Creating a New Version¶

Create a Release:

# Create and push a new tag
git tag v1.1.0
git push origin v1.1.0

GitHub Actions will automatically:
Build the documentation
Create a release on GitHub
Deploy to the versioned URL
Update the version selector

Version Selector¶

The version selector appears in the top navigation and includes: - Current development version (main branch) - All released versions - Easy switching between versions

Configuration¶

GitHub Pages Settings¶

Go to your repository settings
Navigate to "Pages"
Set source to "GitHub Actions"
Ensure the repository is public

Custom Domain (Optional)¶

To use a custom domain:

Add a CNAME file to the docs/ directory:
```
docs.yourdomain.com
```

Configure DNS:

docs.yourdomain.com CNAME manikantesh.github.io

Update mkdocs.yml:
```
site_url: https://docs.yourdomain.com/
```

Troubleshooting¶

Common Issues¶

Build Failures
Check GitHub Actions logs
Verify all dependencies are installed
Ensure markdown files are valid
Version Selector Not Working
Verify git tags exist
Check the version selector script
Ensure proper permissions
Custom Domain Issues
Verify DNS configuration
Check CNAME file
Wait for DNS propagation

Debugging¶

# Test build locally
mkdocs build --clean

# Check for broken links
mkdocs build --strict

# Validate configuration
mkdocs build --verbose

Advanced Configuration¶

Custom Styling¶

Add custom CSS to docs/stylesheets/extra.css:

/* Custom version selector styling */
.version-selector {
    /* Your custom styles */
}

Analytics¶

Add Google Analytics to mkdocs.yml:

extra_javascript:
  - https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID
  - javascripts/analytics.js

Search Configuration¶

Configure search in mkdocs.yml:

plugins:
  - search:
      lang: en
      separator: '[\s\-,:!=\[\]()"/`|]+'
      prebuild_index: true

Security Considerations¶

Repository Visibility: Keep the repository public for GitHub Pages
Secrets: Don't commit sensitive information
Dependencies: Regularly update dependencies
Access Control: Limit who can deploy

Performance Optimization¶

Image Optimization: Compress images before committing
Minification: Enable HTML minification
Caching: Configure proper cache headers
CDN: Consider using a CDN for better performance

Monitoring¶

Health Checks¶

Monitor deployment success rates
Track page load times
Check for broken links
Monitor user engagement

Alerts¶

Set up alerts for: - Failed deployments - High error rates - Performance degradation

Support¶

For deployment issues:

Check GitHub Actions logs
Review this documentation
Open an issue on GitHub
Contact the maintainers

Best Practices¶

Regular Updates: Keep documentation current
Version Control: Use semantic versioning
Testing: Test locally before deploying
Backup: Keep backups of important content
Documentation: Document deployment changes

For more information, see the Configuration Guide and Troubleshooting Guide.