From ddb524dccd98da9c12994b0aa68baf54c7f9d6e5 Mon Sep 17 00:00:00 2001 From: arjuuuuunnnnn Date: Thu, 25 Sep 2025 15:49:17 +0530 Subject: [PATCH 1/7] docs update --- .github/workflows/docs.yml | 33 +++++++++++----- mkdocs.yml | 78 +++++++++++++++++++++++++++++++++++++- 2 files changed, 99 insertions(+), 12 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 659c074..1bed729 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,22 +2,30 @@ name: Build and Deploy Docs on: push: - branches: [ master ] + branches: [ master, main, feat/elim-spof ] paths: - 'docs/**' - 'README.md' + - 'mkdocs.yml' workflow_dispatch: jobs: build-and-deploy: runs-on: ubuntu-latest permissions: - contents: write + 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 + steps: - - uses: actions/checkout@v3 + - name: Checkout + uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v4 @@ -27,14 +35,19 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install mkdocs mkdocs-material + pip install -r docs-requirements.txt - name: Build documentation - run: mkdocs build + run: mkdocs build --strict --verbose + + - name: Setup Pages + uses: actions/configure-pages@v3 - - name: Deploy documentation - uses: peaceiris/actions-gh-pages@v3 + - name: Upload artifact + uses: actions/upload-pages-artifact@v2 with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./site - force_orphan: true + path: ./site + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/mkdocs.yml b/mkdocs.yml index df56059..3bdd5ff 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,12 +1,64 @@ -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 + + - User Guide: + - Quick Start: docs/user-guide/quick-start.md + - CLI Reference: docs/user-guide/cli-reference.md + - Application Specification: docs/user-guide/app-spec.md + - Configuration: docs/user-guide/configuration.md + - API Reference: docs/user-guide/api-reference.md + - Troubleshooting: docs/user-guide/troubleshooting.md + + - Developer Guide: + - Architecture Overview: docs/developer-guide/architecture.md + - Core Components: docs/developer-guide/components.md + - Leader Election: docs/developer-guide/leader-election.md + - Database Schema: docs/developer-guide/database.md + - Scaling Algorithm: docs/developer-guide/scaling.md + - Health Monitoring: docs/developer-guide/health.md + - Load Balancing: docs/developer-guide/load-balancing.md + - Development Setup: docs/developer-guide/development.md + - Extensions: docs/developer-guide/extensions.md + + - Examples: + - Sample Applications: docs/examples/applications.md theme: name: material + palette: + # Palette toggle for light mode + - 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 +67,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 From 2458327d721d335c6c62bc8534896c33fb0ae491 Mon Sep 17 00:00:00 2001 From: arjuuuuunnnnn Date: Thu, 25 Sep 2025 15:50:52 +0530 Subject: [PATCH 2/7] docs version fixed --- .github/workflows/docs.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 1bed729..fad586e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -28,7 +28,7 @@ jobs: uses: actions/checkout@v4 - name: Set up Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: '3.x' @@ -41,13 +41,13 @@ jobs: run: mkdocs build --strict --verbose - name: Setup Pages - uses: actions/configure-pages@v3 + uses: actions/configure-pages@v4 - name: Upload artifact - uses: actions/upload-pages-artifact@v2 + uses: actions/upload-pages-artifact@v3 with: path: ./site - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v2 + uses: actions/deploy-pages@v4 From aaea01806d0687792473861f9e1b05c7e32238c1 Mon Sep 17 00:00:00 2001 From: arjuuuuunnnnn Date: Thu, 25 Sep 2025 15:52:11 +0530 Subject: [PATCH 3/7] docs version fixed --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3a253e8..dc06b76 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AutoServe Documentation -Welcome to AutoServe - A lightweight container orchestration and auto-scaling platform designed for web applications. +Welcome to AutoServe - A lightweight container orchestration and auto-scaling platform designed for web applications ## Documentation Structure From eedcdeb85feba22da9ec3b749855349886fe4a29 Mon Sep 17 00:00:00 2001 From: arjuuuuunnnnn Date: Thu, 25 Sep 2025 15:54:05 +0530 Subject: [PATCH 4/7] removed docs reqs and hardcoded instead --- .github/workflows/docs.yml | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index fad586e..01fc46a 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -35,7 +35,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install -r docs-requirements.txt + pip install mkdocs mkdocs-material - name: Build documentation run: mkdocs build --strict --verbose diff --git a/README.md b/README.md index dc06b76..3a253e8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AutoServe Documentation -Welcome to AutoServe - A lightweight container orchestration and auto-scaling platform designed for web applications +Welcome to AutoServe - A lightweight container orchestration and auto-scaling platform designed for web applications. ## Documentation Structure From 2e4db1e515c76ae8ca7a9c3b5be8816976a82f44 Mon Sep 17 00:00:00 2001 From: arjuuuuunnnnn Date: Thu, 25 Sep 2025 15:59:51 +0530 Subject: [PATCH 5/7] relative paths given for mkdocs --- docs/examples/applications.md | 2 +- docs/index.md | 64 ++++++++++++++++++++++++++++++++++ docs/user-guide/quick-start.md | 2 +- mkdocs.yml | 34 +++++++++--------- 4 files changed, 83 insertions(+), 19 deletions(-) create mode 100644 docs/index.md 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 3bdd5ff..eed7993 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,29 +6,29 @@ repo_url: https://github.com/arjuuuuunnnnn/AutoServe repo_name: arjuuuuunnnnn/AutoServe nav: - - Home: README.md + - Home: index.md - User Guide: - - Quick Start: docs/user-guide/quick-start.md - - CLI Reference: docs/user-guide/cli-reference.md - - Application Specification: docs/user-guide/app-spec.md - - Configuration: docs/user-guide/configuration.md - - API Reference: docs/user-guide/api-reference.md - - Troubleshooting: docs/user-guide/troubleshooting.md + - 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: docs/developer-guide/architecture.md - - Core Components: docs/developer-guide/components.md - - Leader Election: docs/developer-guide/leader-election.md - - Database Schema: docs/developer-guide/database.md - - Scaling Algorithm: docs/developer-guide/scaling.md - - Health Monitoring: docs/developer-guide/health.md - - Load Balancing: docs/developer-guide/load-balancing.md - - Development Setup: docs/developer-guide/development.md - - Extensions: docs/developer-guide/extensions.md + - 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: docs/examples/applications.md + - Sample Applications: examples/applications.md theme: name: material From 2007935e69abadf5f8daf14d17d183bbdbfac0ad Mon Sep 17 00:00:00 2001 From: arjuuuuunnnnn Date: Thu, 25 Sep 2025 16:01:58 +0530 Subject: [PATCH 6/7] relative paths given for mkdocs --- .github/workflows/docs.yml | 6 ++++++ mkdocs.yml | 1 - 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 01fc46a..ec216d9 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -12,6 +12,12 @@ on: jobs: build-and-deploy: runs-on: ubuntu-latest + + # Environment is required for GitHub Pages deployment + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + permissions: contents: read pages: write diff --git a/mkdocs.yml b/mkdocs.yml index eed7993..2c3f424 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,7 +33,6 @@ nav: theme: name: material palette: - # Palette toggle for light mode - scheme: default primary: blue accent: blue From fa85436a2e3522c24a8ec5d359f8d851d18a1593 Mon Sep 17 00:00:00 2001 From: arjuuuuunnnnn Date: Thu, 25 Sep 2025 16:06:09 +0530 Subject: [PATCH 7/7] docs.yml, branch protection -> deployable only from master --- .github/workflows/docs.yml | 61 +++++++++++++++++++++++++++----------- 1 file changed, 44 insertions(+), 17 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ec216d9..5a1f13c 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,7 +2,13 @@ name: Build and Deploy Docs on: push: - branches: [ master, main, feat/elim-spof ] + branches: [ master, main ] + paths: + - 'docs/**' + - 'README.md' + - 'mkdocs.yml' + pull_request: + branches: [ master, main ] paths: - 'docs/**' - 'README.md' @@ -10,8 +16,39 @@ on: workflow_dispatch: jobs: - build-and-deploy: + # Build job - runs on all branches for validation + build: runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.x' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install mkdocs mkdocs-material + + - name: Build documentation + 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: @@ -30,26 +67,16 @@ jobs: cancel-in-progress: false steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Set up Python - uses: actions/setup-python@v5 + - name: Download build artifact + uses: actions/download-artifact@v4 with: - python-version: '3.x' - - - name: Install dependencies - run: | - python -m pip install --upgrade pip - pip install mkdocs mkdocs-material - - - name: Build documentation - run: mkdocs build --strict --verbose + name: docs-site + path: ./site - name: Setup Pages uses: actions/configure-pages@v4 - - name: Upload artifact + - name: Upload pages artifact uses: actions/upload-pages-artifact@v3 with: path: ./site