diff --git a/CHANGELOG.md b/CHANGELOG.md index 95d5402..9b142d9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Documentation +- Fixed README badge links to point to active CI workflow status and official technology specifications. +- Corrected git clone command and ADR relative markdown paths in README. +- Added ADR 0008 establishing multi-platform deployment strategy across Self-Hosting, PaaS (Railway/Render), Kubernetes, and Major Cloud Providers (AWS/GCP/Azure/OCI). +- Updated roadmap and architecture specifications with multi-target hosting matrix. + --- ## [1.1.0] - 2026-08-27 diff --git a/README.md b/README.md index 69ced1c..e5dc44e 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@
-[![Build Status](https://img.shields.io/badge/Build-Passing-2ea44f?style=for-the-badge&logo=github-actions&logoColor=white)]() -[![Java 25](https://img.shields.io/badge/Java-25%20(LTS)-f89820?style=for-the-badge&logo=openjdk&logoColor=white)]() -[![Spring Boot 4](https://img.shields.io/badge/Spring%20Boot-4.0.0-6db33f?style=for-the-badge&logo=springboot&logoColor=white)]() -[![PostgreSQL 17](https://img.shields.io/badge/PostgreSQL-17-4169e1?style=for-the-badge&logo=postgresql&logoColor=white)]() -[![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-OTel%20Standard-4a154b?style=for-the-badge&logo=opentelemetry&logoColor=white)]() +[![CI Build](https://img.shields.io/github/actions/workflow/status/shashankch/task-master/ci.yml?branch=main&style=for-the-badge&logo=github-actions&logoColor=white&label=CI%20Build)](https://github.com/shashankch/task-master/actions/workflows/ci.yml) +[![Java 25](https://img.shields.io/badge/Java-25%20(LTS)-f89820?style=for-the-badge&logo=openjdk&logoColor=white)](https://openjdk.org/projects/jdk/25/) +[![Spring Boot 4](https://img.shields.io/badge/Spring%20Boot-4.0.0-6db33f?style=for-the-badge&logo=springboot&logoColor=white)](https://spring.io/projects/spring-boot) +[![PostgreSQL 17](https://img.shields.io/badge/PostgreSQL-17-4169e1?style=for-the-badge&logo=postgresql&logoColor=white)](https://www.postgresql.org/) +[![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-OTel%20Standard-4a154b?style=for-the-badge&logo=opentelemetry&logoColor=white)](https://opentelemetry.io/) [![OpenAPI 3.1](https://img.shields.io/badge/OpenAPI-3.1%20Spec-85ea2d?style=for-the-badge&logo=openapiinitiative&logoColor=black)](./docs/api/openapi.yaml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](./LICENSE) @@ -112,7 +112,7 @@ TaskMaster is an enterprise-grade collaborative task tracking platform designed ### 1. Clone Repository ```bash -git clone https://github.com/shashankchandel/task-master.git +git clone https://github.com/shashankch/task-master.git cd task-master ``` @@ -206,7 +206,7 @@ Track development progress across engineering phases: - ✅ **Phase 6: Production Hardening, Security Remediation & Open Standards** (Persistent RSA Keys, OTel Tracing, OpenAPI 3.1 YAML, S3 Client Engine, IDOR Authorization) - ⬜ **Phase 7: Advanced Search & Analytics** (Elasticsearch Cluster Sync, Velocity Metrics, Audit Trails) - ⬜ **Phase 8: Performance & Reliability** (Distributed Redis Rate Limiting, Resilience4j Circuit Breaking) -- ⬜ **Phase 9: DevOps & Cloud Deployment** (Distroless Containerization, Kubernetes HPA Manifests, GitHub Actions CI/CD) +- ⬜ **Phase 9: DevOps, Cloud & Multi-Platform Deployment** (Self-Hosting, PaaS Railway/Render, Distroless Containerization, Kubernetes HPA, AWS/GCP/Azure/OCI) - ⬜ **Phase 10: Extended Platform Capabilities** (DAG Task Dependencies, Recurring Automation, Kanban Positional Engine) - ⬜ **Phase 11: Modern Collaborative Web Application (Frontend)** (Next.js 15, React 19, Tailwind CSS, Kanban UI, Real-time WebSocket Client) @@ -221,12 +221,13 @@ For in-depth milestone specifications, see [`docs/ROADMAP.md`](./docs/ROADMAP.md - 📋 **Static OpenAPI 3.1 YAML Schema**: [`docs/api/openapi.yaml`](./docs/api/openapi.yaml) - 🏛️ **Architecture Decision Records (ADRs)**: [`docs/adr/`](./docs/adr/) - [ADR 0001: Modular Monolith Architecture](./docs/adr/0001-modular-monolith.md) - - [ADR 0002: PostgreSQL & Flyway Strategy](./docs/adr/0002-postgresql-flyway.md) + - [ADR 0002: PostgreSQL & Flyway Strategy](./docs/adr/0002-postgresql.md) - [ADR 0003: Hexagonal Architecture Boundaries](./docs/adr/0003-hexagonal-architecture.md) - - [ADR 0004: Event-Driven Architecture](./docs/adr/0004-event-driven-architecture.md) + - [ADR 0004: Event-Driven Architecture with Spring Cloud Stream](./docs/adr/0004-spring-cloud-stream.md) - [ADR 0005: Universal OpenAI-Compatible AI Strategy](./docs/adr/0005-ai-provider-strategy.md) - [ADR 0006: OpenTelemetry (OTel) Standard for Observability](./docs/adr/0006-opentelemetry-vendor-neutrality.md) - [ADR 0007: Pluggable Free-Tier & Open-Source First Strategy](./docs/adr/0007-free-tier-pluggable-infrastructure.md) + - [ADR 0008: Multi-Platform Cloud, PaaS & Container Deployment Strategy](./docs/adr/0008-multi-platform-cloud-paas-deployment-strategy.md) - 🤝 **Contributing Guidelines**: [`CONTRIBUTING.md`](./CONTRIBUTING.md) --- diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index c43298a..fa2a867 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -69,11 +69,14 @@ A trackable overview of delivery milestones and planned capabilities for the Tas - Circuit breaking and fault tolerance via Resilience4j - Idempotency key tracking for non-idempotent mutations -- ⬜ **Phase 9: DevOps & Cloud Deployment** - - Multi-stage minimal containerization - - Production Kubernetes manifests (Deployments, Services, HPA, ConfigMaps) - - GitHub Actions automated CI/CD pipeline - - Full observability stack (OpenTelemetry tracing, Prometheus metrics, Grafana dashboards) +- ⬜ **Phase 9: DevOps, Cloud & Multi-Platform Deployment** + - Multi-stage minimal containerization with Distroless / Eclipse Temurin Java 25 + - Self-hosting & local orchestration with single-command Docker Compose stack + - 1-Click PaaS deployment blueprints (`railway.json` and `render.yaml` with dynamic SSL & port injection) + - Production Kubernetes manifests in `k8s/` (Deployments, Services, Ingress with WebSocket upgrades, HPA, ConfigMaps, Secrets) + - Major cloud deployment blueprints (AWS ECS Fargate / RDS / S3, Google Cloud Run, Azure Container Apps, OCI Ampere) + - GitHub Actions automated CI/CD pipeline for building, testing, and container image publishing + - Full observability visualization (OpenTelemetry OTLP traces in Jaeger, Prometheus metrics, Grafana dashboards) - ⬜ **Phase 10: Extended Platform Capabilities** - Directed Acyclic Graph (DAG) task dependency engine with cycle detection diff --git a/docs/adr/0008-multi-platform-cloud-paas-deployment-strategy.md b/docs/adr/0008-multi-platform-cloud-paas-deployment-strategy.md new file mode 100644 index 0000000..1706823 --- /dev/null +++ b/docs/adr/0008-multi-platform-cloud-paas-deployment-strategy.md @@ -0,0 +1,37 @@ +# ADR 0008: Multi-Platform Cloud, PaaS & Container Deployment Strategy + +## Status +Accepted + +## Context +TaskMaster is designed as a cloud-native collaborative task platform that must run seamlessly across diverse hosting environments—from a developer's local laptop to enterprise Kubernetes clusters and modern Platform-as-a-Service (PaaS) providers—without requiring code modifications or proprietary vendor lock-in. + +Modern engineering teams require flexibility across four distinct deployment tiers: +1. **Self-Hosting & Local Development**: Instant, zero-cloud-cost stack orchestration on bare metal or local workstations. +2. **Modern PaaS (Railway, Render, Fly.io)**: 1-click deployment with automated SSL, dynamic port binding, and managed database provisioning. +3. **Containerization & Orchestration (Docker & Kubernetes)**: Production-grade autoscaling, rolling zero-downtime deployments, and pod health monitoring. +4. **Major Cloud Hyperscalers (AWS, GCP, Azure, OCI)**: Scalable, enterprise infrastructure leveraging managed relational databases, object storage, and distributed telemetry. + +## Decision +We adopt a **Unified Multi-Platform Deployment Strategy** in Phase 9 that guarantees portability across all four deployment tiers while maintaining 100% backward compatibility with our existing local development workflow: + +| Deployment Tier | Target Platform | Orchestration & Artifacts | Configuration & Ingress Mechanism | +|:---|:---|:---|:---| +| **1. Self-Hosting & Local** | Local workstation / Bare-metal VM | `docker-compose.yml` (PostgreSQL 17, Redis 7, RabbitMQ 4, MinIO, Jaeger, Elasticsearch) | `dev` profile (`application-dev.yml`), localhost port bindings | +| **2. Modern PaaS** | Railway, Render, Fly.io | `railway.json`, `render.yaml` Infrastructure-as-Code blueprints | `prod` profile (`application-prod.yml`), dynamic `${PORT:8080}` injection, managed PostgreSQL/Redis SSL connections | +| **3. Container Orchestration** | Kubernetes (EKS, GKE, AKS, Vanilla K8s) | Minimal Distroless Java 25 Dockerfile, production `k8s/` manifests (Deployments, Services, Ingress, HPA, ConfigMaps, Secrets) | Native `/actuator/health/liveness` and `/actuator/health/readiness` probes, WebSocket upgrade annotations | +| **4. Cloud Hyperscalers** | AWS ECS Fargate, Google Cloud Run, Azure Container Apps, OCI Ampere | Multi-arch container image + Terraform / Cloud blueprints | Cloud-managed Aurora/Cloud SQL, ElastiCache, S3/R2 storage, and OpenTelemetry OTLP exporters | + +### Architectural Enablers +- **12-Factor App Methodology**: All infrastructure connection strings, credentials, and tuning parameters in `application-prod.yml` bind to standard environment variables (`SPRING_DATASOURCE_URL`, `SPRING_REDIS_HOST`, `AWS_S3_ENDPOINT`, `PORT`). +- **Dynamic Port Ingress**: The application server binds to `server.port=${PORT:8080}`, automatically adapting to PaaS ingress proxies (Railway, Render, Cloud Run). +- **Orchestrator Probes**: Spring Boot Actuator exposes dedicated liveness and readiness probe groups (`/actuator/health/liveness`, `/actuator/health/readiness`) for automated container restarts and zero-downtime routing. + +## Consequences +### Positive +- **Total Operational Portability**: Deployable anywhere—from a single laptop using Docker Compose to global Kubernetes clusters or zero-management PaaS. +- **Zero Code Refactoring**: Switching between local Docker, Railway, Kubernetes, or AWS ECS requires only environment variable configuration. +- **Production Resilience**: Multi-stage distroless container images minimize attack surface, reduce image size, and leverage Class Data Sharing (CDS) for rapid cold-start times. + +### Negative +- Requires maintaining deployment blueprints (`railway.json`, `render.yaml`, and `k8s/` manifests) alongside application code. diff --git a/docs/architecture.md b/docs/architecture.md index 38ffee9..0bb6b23 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -722,6 +722,17 @@ flowchart TB PN --> OBJ ``` +### Multi-Platform Deployment Targets + +| Deployment Target | Orchestration / Artifacts | Environment Profiles & Ingress | +|:---|:---|:---| +| **Local / Self-Hosting** | `docker-compose.yml` (PostgreSQL 17, Redis, RabbitMQ, MinIO, Jaeger, Elasticsearch) | `dev` profile (`application-dev.yml`), localhost port mapping | +| **Modern PaaS (Railway / Render)** | `railway.json` / `render.yaml` with dynamic `PORT` injection & managed addon DBs | `prod` profile (`application-prod.yml`), dynamic SSL DB connection strings | +| **Kubernetes (K8s)** | Multi-stage Distroless Java 25 Image, `k8s/` manifests (Deployment, Service, Ingress, HPA) | `prod` profile, Kubernetes Liveness/Readiness probes (`/actuator/health/*`) | +| **Cloud (AWS/GCP/Azure/OCI)** | AWS ECS Fargate / GCP Cloud Run / Azure Container Apps / OCI Ampere A1 Compute | Cloud-managed Aurora/RDS, ElastiCache, S3, and OTLP OpenTelemetry exporters | + +For detailed architectural trade-offs and design rationale, see [ADR 0008: Multi-Platform Cloud, PaaS & Container Deployment Strategy](./adr/0008-multi-platform-cloud-paas-deployment-strategy.md). + --- ## 11. Technology Baseline Matrix