Create chart

2025-08-05 14:41:45 +08:00
parent b24ced7bc9
commit 2923d87a92
18 changed files with 915 additions and 0 deletions
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -0,0 +1,47 @@
+# ROADMAP
+
+This document outlines the roadmap of tasks done by claude in this project.
+
+## Development Workflow
+
+1. **Task Planning**
+
+- Study existing code and documentation and understand the current state
+- Update `ROADMAP.md` to include the new task
+
+2. **Task Creation**
+
+- Study existing code and documentation and understand the current state
+- Create a new task in `docs/tasks/` directory
+- Name format: `XX-<task-name>.md` (e.g., `01-setup-docker.md`)
+- Include high level specification of the task, including:
+  - Relevant files
+  - Purpose and goals
+  - Key components and technologies involved
+  - Expected outcomes and deliverables
+  - Tests (If applicable)
+  - Implementation steps
+  - TODO items and subtasks
+- Note that this is a new task, the TODO items should be unchecked.
+
+3. **Task Implementation**
+
+- Study existing code and documentation and understand the current state
+- Follow the specification from the tasks file
+- Implement features and functionality
+- Update step progress within the task file after each step
+
+4. **Roadmap Update**
+
+- Mark completed tasks with [X] in the `ROADMAP.md` file
+- Add reference to the task file (e.g. See [01-setup-docker.md](docs/tasks/01-setup-docker.md))
+
+## Development Tasks
+
+- [x] **Task 00: Helm Chart Deployment** - See [00-helm-chart-deployment.md](docs/tasks/00-helm-chart-deployment.md)
+  - Create a Helm chart for Kubernetes deployment of the application.
+  - Create `charts/` directory structure with standard Helm chart layout (Chart.yaml, values.yaml, templates/)
+  - Define Kubernetes deployment manifests for the Bun-based API server with proper resource limits and health checks
+  - Configure PostgreSQL database deployment or external database connection options in the chart
+  - Set up ingress configuration with configurable domain and TLS certificate management
+  - Add comprehensive values.yaml with environment-specific overrides for development, staging, and production deployments
--- a/docs/tasks/00-helm-chart-deployment.md
+++ b/docs/tasks/00-helm-chart-deployment.md
@@ -0,0 +1,182 @@
+# Task 00: Helm Chart Deployment
+
+## Overview
+
+Create a comprehensive Helm chart for Kubernetes deployment of the Bun-based API server application. This task will enable containerized deployment across different environments (staging, production) with proper configuration management and scalability.
+
+## Relevant Files
+
+- `api/Dockerfile` - Existing container definition for the Bun API server
+- `api/package.json` - Application dependencies and metadata
+- `api/src/index.ts` - Main application entry point using Effect-TS
+- `docker-compose.yml` - Current PostgreSQL development setup
+- `charts/` - New directory for Helm chart files (to be created)
+
+## Purpose and Goals
+
+- Enable Kubernetes deployment of the Bun API server across multiple environments
+- Provide configurable database connection options (embedded PGLite vs external PostgreSQL)
+- Implement proper resource management, health checks, and scaling capabilities
+- Support ingress configuration with TLS certificate management
+- Allow environment-specific customization through values files
+
+## Key Components and Technologies
+
+- **Helm 3.x** - Kubernetes package manager for templating and deployment
+- **Kubernetes** - Container orchestration platform
+- **Bun Runtime** - JavaScript/TypeScript runtime (oven/bun:1.2.19-alpine base image)
+- **Effect-TS** - Functional programming framework used by the API
+- **PostgreSQL** - Database option for production deployments
+- **Ingress Controller** - For external traffic routing and TLS termination
+
+## Expected Outcomes and Deliverables
+
+### Chart Structure
+
+```
+charts/system/
+├── Chart.yaml              # Chart metadata and version information
+├── values.yaml             # Default configuration values
+├── values-staging.yaml     # Staging environment overrides
+├── values-prod.yaml        # Production environment overrides
+└── templates/
+    ├── deployment.yaml     # API server deployment manifest
+    ├── service.yaml        # Service definition for API endpoints
+    ├── ingress.yaml        # Ingress configuration with TLS
+    ├── configmap.yaml      # Configuration data for the application
+    ├── secret.yaml         # Sensitive configuration (database credentials)
+    ├── hpa.yaml            # Horizontal Pod Autoscaler (optional)
+    └── NOTES.txt           # Post-installation instructions
+```
+
+### Key Features
+
+- **Multi-environment support** with environment-specific values files
+- **Database flexibility** - configurable PostgreSQL or PGLite usage
+- **Resource management** with CPU/memory limits and requests
+- **Health checks** - readiness and liveness probes for the API server
+- **Horizontal scaling** capability with HPA configuration
+- **Ingress configuration** with configurable domains and TLS certificates
+- **Security** - non-root container execution and proper secret management
+
+## Tests
+
+### Validation Tests
+
+- [x] Helm chart linting (`helm lint charts/system/`)
+- [x] Template rendering validation (`helm template charts/system/`)
+- [x] Values schema validation for all environment files
+- [x] Kubernetes manifest syntax validation
+
+## Implementation Steps
+
+### Step 1: Create Chart Foundation
+
+- [x] Create `charts/system/` directory structure
+- [x] Initialize `Chart.yaml` with proper metadata
+- [x] Create base `values.yaml` with comprehensive default values
+- [x] Set up templating helpers in `_helpers.tpl`
+
+### Step 2: Core Kubernetes Manifests
+
+- [x] Create `deployment.yaml` template for the Bun API server
+  - Configure container image and tag templating
+  - Set up resource limits and requests
+  - Add environment variable configuration
+  - Implement readiness and liveness probes
+- [x] Create `service.yaml` template for API endpoints
+  - Configure service type and port mapping
+  - Add service annotations for load balancer configuration
+- [x] Create `configmap.yaml` for application configuration
+  - Environment-specific settings
+  - Database connection parameters
+
+### Step 3: Database Configuration
+
+- [x] Add PostgreSQL database deployment option in templates
+  - External database connection configuration
+- [x] Configure PGLite embedded database option
+  - Volume mounting for data persistence
+  - Memory/storage configuration
+- [x] Create `secret.yaml` template for database credentials
+  - Templated secret generation
+  - External secret integration capabilities
+
+### Step 4: Ingress and Networking
+
+- [x] Create `ingress.yaml` template
+  - Configurable host domains
+  - TLS certificate management (cert-manager integration)
+  - Path-based routing configuration
+  - Ingress class configuration
+- [ ] Add network policies (optional)
+  - Database access restrictions
+  - External traffic controls
+
+### Step 5: Scaling and Performance
+
+- [x] Create `hpa.yaml` template for horizontal pod autoscaling
+  - CPU and memory-based scaling triggers
+  - Custom metrics integration capabilities
+- [ ] Add resource monitoring configurations
+  - ServiceMonitor for Prometheus (if applicable)
+  - Logging configuration
+
+### Step 6: Environment-Specific Values
+
+- [x] Create `values-staging.yaml`
+  - Multi-replica setup
+  - External PostgreSQL configuration
+  - Production-like resource allocation
+  - Staging domain configuration
+- [x] Create `values-prod.yaml`
+  - High availability configuration
+  - External PostgreSQL with connection pooling
+  - Strict resource limits and security policies
+  - Production domain and TLS settings
+
+### Step 7: Documentation and Validation
+
+- [x] Create comprehensive `NOTES.txt` with deployment instructions
+- [x] Add inline documentation to all template files
+- [ ] Create deployment guide in `charts/system/README.md`
+- [x] Validate all templates with different values files
+
+## TODO Items and Subtasks
+
+### Prerequisites
+
+- [ ] Verify Kubernetes cluster access and Helm installation
+- [ ] Determine ingress controller type (nginx, traefik, etc.)
+- [ ] Identify certificate management strategy (cert-manager, manual)
+- [ ] Choose container registry for image storage
+
+### Database Strategy
+
+- [ ] Define database migration strategy for Kubernetes deployment
+- [ ] Configure backup and restore procedures for PostgreSQL
+- [ ] Set up database monitoring and alerting
+- [ ] Plan for database scaling and connection pooling
+
+### Security Considerations
+
+- [ ] Implement Pod Security Standards compliance
+- [ ] Configure RBAC permissions for the application
+- [ ] Set up secret rotation strategies
+- [ ] Add network security policies
+
+### Monitoring and Observability
+
+- [ ] Integrate with logging infrastructure (Fluentd, Logstash)
+- [ ] Add metrics collection (Prometheus integration)
+- [ ] Configure distributed tracing (if applicable)
+- [ ] Set up alerting rules for application health
+
+### CI/CD Integration
+
+- [ ] Create GitHub Actions workflow for chart testing
+- [ ] Set up automated chart versioning and publishing
+- [ ] Add chart security scanning
+- [ ] Implement automated deployment pipelines
+
+This task will provide a production-ready Kubernetes deployment solution for the Bun-based API server, enabling scalable and manageable deployments across multiple environments.