diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 659c074..5a1f13c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,25 +2,29 @@ name: Build and Deploy Docs on: push: - branches: [ master ] + branches: [ master, main ] paths: - 'docs/**' - 'README.md' + - 'mkdocs.yml' + pull_request: + branches: [ master, main ] + paths: + - 'docs/**' + - 'README.md' + - 'mkdocs.yml' workflow_dispatch: jobs: - build-and-deploy: + # Build job - runs on all branches for validation + build: runs-on: ubuntu-latest - permissions: - contents: write - pages: write - id-token: write - steps: - - uses: actions/checkout@v3 + - name: Checkout + uses: actions/checkout@v4 - name: Set up Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.x' @@ -30,11 +34,53 @@ jobs: pip install mkdocs mkdocs-material - name: Build documentation - run: mkdocs build + run: mkdocs build --strict --verbose + + - name: Upload build artifact + uses: actions/upload-artifact@v4 + with: + name: docs-site + path: ./site + + # Deploy job - only runs on main branches + deploy: + # Only deploy on main/master branches, not on PRs or feature branches + if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') + + runs-on: ubuntu-latest + needs: build + + # Environment is required for GitHub Pages deployment + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + permissions: + contents: read + pages: write + id-token: write + + # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. + # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. + concurrency: + group: "pages" + cancel-in-progress: false - - name: Deploy documentation - uses: peaceiris/actions-gh-pages@v3 + steps: + - name: Download build artifact + uses: actions/download-artifact@v4 with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./site - force_orphan: true + name: docs-site + path: ./site + + - name: Setup Pages + uses: actions/configure-pages@v4 + + - name: Upload pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./site + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/docs/examples/applications.md b/docs/examples/applications.md index bcbcfdc..81a38ea 100644 --- a/docs/examples/applications.md +++ b/docs/examples/applications.md @@ -902,4 +902,4 @@ These examples demonstrate various patterns and configurations for different typ --- -**Next Steps**: Explore [Deployment Scenarios](deployments.md) for different infrastructure patterns. \ No newline at end of file +**Next Steps**: Explore [Configuration Guide](../user-guide/configuration.md) for advanced deployment settings. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..db20688 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,64 @@ +# AutoServe Documentation + +Welcome to AutoServe - A lightweight container orchestration and auto-scaling platform designed for web applications. + +## Documentation Structure + +### For Users +- [Quick Start Guide](user-guide/quick-start.md) - Get up and running in minutes +- [CLI Reference](user-guide/cli-reference.md) - Complete command-line interface documentation +- [Application Specification](user-guide/app-spec.md) - How to define your applications +- [Configuration Guide](user-guide/configuration.md) - Environment and scaling configuration +- [REST API Reference](user-guide/api-reference.md) - HTTP API endpoints and usage +- [Troubleshooting](user-guide/troubleshooting.md) - Common issues and solutions + +### For Developers +- [Architecture Overview](developer-guide/architecture.md) - System design and components +- [Core Components](developer-guide/components.md) - Detailed component documentation +- [Leader Election](developer-guide/leader-election.md) - Distributed controller and high availability +- [Database Schema](developer-guide/database.md) - State management and persistence +- [Scaling Algorithm](developer-guide/scaling.md) - Auto-scaling logic and policies +- [Health Monitoring](developer-guide/health.md) - Health check system +- [Load Balancing](developer-guide/load-balancing.md) - Nginx integration and routing +- [Development Setup](developer-guide/development.md) - Contributing to AutoServe +- [Extension Guide](developer-guide/extensions.md) - Adding new features + +### Examples +- [Sample Applications](examples/applications.md) - Real-world application examples + +## What is AutoServe? + +AutoServe is a container orchestration platform that provides: + +- **Intelligent Auto-Scaling**: Automatically scales your applications based on CPU, memory, RPS, latency, and connection metrics +- **Load Balancing**: Dynamic Nginx configuration with health-aware routing +- **Health Monitoring**: Continuous health checks with automatic recovery +- **Simple Deployment**: YAML-based application specifications +- **RESTful API**: Complete programmatic control +- **High Availability**: Distributed controller with leader election eliminates single points of failure +- **Database HA**: PostgreSQL-based state management with primary-replica replication + +## Key Features + +- **Container Orchestration**: Docker-based application lifecycle management +- **Multi-Metric Auto-Scaling**: CPU, memory, RPS, latency, and connection-based scaling +- **Dynamic Load Balancing**: Nginx with health-aware routing and SSL termination +- **Health Monitoring**: Continuous health checks with automatic recovery +- **Distributed Architecture**: 3-node controller cluster with leader election +- **High Availability**: Automatic failover and split-brain prevention +- **CLI and REST API**: Complete programmatic and command-line interfaces +- **Persistent State**: PostgreSQL with primary-replica setup +- **Event Logging**: Complete audit trail and cluster event tracking +- **Resource Management**: CPU/memory constraints and intelligent scaling policies + +## Quick Links + +- [Installation](user-guide/quick-start.md#installation) +- [Your First Application](user-guide/quick-start.md#deploying-your-first-app) +- [CLI Commands](user-guide/cli-reference.md) +- [API Endpoints](user-guide/api-reference.md) +- [Architecture](developer-guide/architecture.md) + +--- + +*AutoServe v1.0.0 - Built for simplicity, designed for scale* \ No newline at end of file diff --git a/docs/user-guide/quick-start.md b/docs/user-guide/quick-start.md index 39d6e61..9411b5c 100644 --- a/docs/user-guide/quick-start.md +++ b/docs/user-guide/quick-start.md @@ -283,7 +283,7 @@ Now that you have AutoServe running: 2. **Understand App Specs**: Read the [Application Specification](app-spec.md) guide 3. **Explore the API**: See the [REST API Reference](api-reference.md) 4. **Configure Scaling**: Dive into [Configuration Guide](configuration.md) -5. **Monitor Applications**: Learn about [monitoring and metrics](monitoring.md) +5. **Monitor Applications**: Learn about [health monitoring](../developer-guide/health.md) ## Getting Help diff --git a/mkdocs.yml b/mkdocs.yml index df56059..2c3f424 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,12 +1,63 @@ -site_name: AutoServe +site_name: AutoServe Documentation site_url: https://arjuuuuunnnnn.github.io/AutoServe/ -use_directory_urls: false +site_description: AutoServe - Container Orchestration and Auto-Scaling Platform +use_directory_urls: true +repo_url: https://github.com/arjuuuuunnnnn/AutoServe +repo_name: arjuuuuunnnnn/AutoServe nav: - - Home: README.md + - Home: index.md + + - User Guide: + - Quick Start: user-guide/quick-start.md + - CLI Reference: user-guide/cli-reference.md + - Application Specification: user-guide/app-spec.md + - Configuration: user-guide/configuration.md + - API Reference: user-guide/api-reference.md + - Troubleshooting: user-guide/troubleshooting.md + + - Developer Guide: + - Architecture Overview: developer-guide/architecture.md + - Core Components: developer-guide/components.md + - Leader Election: developer-guide/leader-election.md + - Database Schema: developer-guide/database.md + - Scaling Algorithm: developer-guide/scaling.md + - Health Monitoring: developer-guide/health.md + - Load Balancing: developer-guide/load-balancing.md + - Development Setup: developer-guide/development.md + - Extensions: developer-guide/extensions.md + + - Examples: + - Sample Applications: examples/applications.md theme: name: material + palette: + - scheme: default + primary: blue + accent: blue + toggle: + icon: material/brightness-7 + name: Switch to dark mode + + # Palette toggle for dark mode + - scheme: slate + primary: blue + accent: blue + toggle: + icon: material/brightness-4 + name: Switch to light mode + + features: + - navigation.tabs + - navigation.sections + - navigation.expand + - navigation.top + - search.highlight + - search.share + - content.code.copy + - content.code.annotate + site_dir: site plugins: @@ -15,4 +66,26 @@ plugins: markdown_extensions: - toc: permalink: true + toc_depth: 3 + - admonition + - pymdownx.details + - pymdownx.superfences + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.tabbed: + alternate_style: true + - attr_list + - md_in_html + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/arjuuuuunnnnn/AutoServe + version: + provider: mike