admin
008f0fd7ab
- Update Docker base images: node:22-alpine → node:24-alpine - Add engines.node >=24.0.0 to package.json files - Create .nvmrc files with 24.15.0 - Update CI workflow to use node-version: 24.15.0 - Fix jest-e2e.json for uuid@13 ES Module compatibility Validation: - Backend unit tests: 340/340 passed - Frontend unit tests: 137/137 passed - Frontend build: successful (39 static pages)
308 lines
9.5 KiB
Markdown
308 lines
9.5 KiB
Markdown
# Implementation Plan: Node.js Upgrade v22.20.0 → v24.15.0
|
|
|
|
**Branch**: `103-node-upgrade` | **Date**: 2026-05-05 | **Spec**: [spec.md](./spec.md)
|
|
|
|
**Input**: Feature specification for upgrading Node.js from v22.20.0 to v24.15.0
|
|
|
|
## Summary
|
|
|
|
Upgrade NAP-DMS backend (NestJS) and frontend (Next.js) build environments from Node.js v22.20.0 to v24.15.0 LTS. This upgrade ensures continued security support through 2027, enables Next.js 15+ and React 19 features, and provides performance improvements. The implementation involves Docker image updates, CI/CD pipeline changes, dependency validation, and comprehensive testing with a documented rollback procedure.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Node.js v24.15.0 LTS (current LTS as of 2025)
|
|
**Primary Dependencies**:
|
|
- Backend: NestJS 10.x, TypeScript 5.x, TypeORM 0.3.x
|
|
- Frontend: Next.js 14.x, React 18.x
|
|
- Package Manager: pnpm 9.x
|
|
|
|
**Storage**: N/A (infrastructure upgrade - no data model changes)
|
|
**Testing**:
|
|
- Backend: Jest with Supertest for e2e
|
|
- Frontend: Vitest with React Testing Library
|
|
|
|
**Target Platform**: Linux (QNAP/ASUSTOR NAS), Docker containers with Alpine Linux
|
|
**Project Type**: Web application (backend + frontend)
|
|
**Performance Goals**: API response times within 5% of v22.20.0 baseline
|
|
**Constraints**:
|
|
- 15-minute maximum rollback time
|
|
- Zero-downtime deployment preferred
|
|
- Must maintain compatibility with existing pnpm lockfile
|
|
|
|
**Scale/Scope**:
|
|
- 2 environments (backend + frontend)
|
|
- ~50 native dependencies to validate (bcrypt, sharp, sqlite3, etc.)
|
|
- CI/CD pipelines in Gitea Actions
|
|
|
|
## Constitution Check
|
|
|
|
_เช็คกฎ AGENTS.md ก่อนเริ่ม - Node.js upgrade เป็น infrastructure ไม่มีผลต่อ ADRs หลัก_
|
|
|
|
| ADR | Applicable | Notes |
|
|
|-----|------------|-------|
|
|
| ADR-009 (Schema) | ❌ N/A | No database changes |
|
|
| ADR-019 (UUID) | ❌ N/A | No identifier changes |
|
|
| ADR-016 (Security) | ⚠️ Partial | Verify audit/security libs compile |
|
|
| ADR-007 (Errors) | ❌ N/A | No code changes |
|
|
| ADR-008 (BullMQ) | ⚠️ Partial | Verify BullMQ native deps on v24 |
|
|
|
|
**GATE STATUS**: ✅ PASS - Infrastructure upgrade with minimal code impact
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/100-Infrastructures/103-node-upgrade/
|
|
├── plan.md # This file
|
|
├── research.md # Phase 0: Node.js v24 breaking changes & compatibility
|
|
├── data-model.md # N/A (no data changes)
|
|
├── quickstart.md # Developer upgrade guide
|
|
├── contracts/ # N/A (no API changes)
|
|
└── tasks.md # Phase 2 output (/speckit.tasks)
|
|
```
|
|
|
|
### Source Code (repository root)
|
|
|
|
```text
|
|
backend/
|
|
├── Dockerfile # UPDATE: node:24.15.0-alpine
|
|
├── package.json # UPDATE: engines.node field
|
|
├── .nvmrc # CREATE/UPDATE: 24.15.0
|
|
└── pnpm-lock.yaml # Regenerate on v24
|
|
|
|
frontend/
|
|
├── Dockerfile # UPDATE: node:24.15.0-alpine
|
|
├── package.json # UPDATE: engines.node field
|
|
├── .nvmrc # CREATE/UPDATE: 24.15.0
|
|
└── pnpm-lock.yaml # Regenerate on v24
|
|
|
|
.gitea/workflows/
|
|
├── ci-deploy.yml # UPDATE: node-version: 24.15.0
|
|
|
|
.gitea/
|
|
└── workflows/ # Any additional CI files
|
|
```
|
|
|
|
**Structure Decision**: Infrastructure-focused update touching 2 main directories (backend/, frontend/) plus CI configuration. No new source code directories required.
|
|
|
|
## Phase 0: Research & Unknown Resolution
|
|
|
|
### Research Topics
|
|
|
|
**RT-001: Node.js v24 Breaking Changes**
|
|
- Research: Node.js v24 release notes and breaking changes vs v22
|
|
- Decision: Use v24.15.0 (LTS) which is stable
|
|
- Rationale: LTS ensures stability and long-term support
|
|
- Alternatives: v23 (not LTS), stay on v22 (End-of-Life 2026)
|
|
|
|
**RT-002: Native Module Compatibility**
|
|
- Research: Check bcrypt, sharp, sqlite3, argon2 compatibility with Node.js v24
|
|
- Decision: Test compilation in staging environment first
|
|
- Rationale: Native modules using N-API v8+ are generally compatible
|
|
- Alternatives: Use pure-JS alternatives (slower), pin to older versions
|
|
|
|
**RT-003: pnpm Compatibility**
|
|
- Research: pnpm 9.x compatibility with Node.js v24
|
|
- Decision: pnpm 9.x fully supports Node.js v18-v24
|
|
- Rationale: pnpm maintains compatibility across Node.js LTS versions
|
|
- Alternatives: Switch to npm/yarn (unnecessary disruption)
|
|
|
|
**RT-004: Docker Image Availability**
|
|
- Research: `node:24.15.0-alpine` image availability and size
|
|
- Decision: Use `node:24.15.0-alpine3.21` (or latest alpine)
|
|
- Rationale: Alpine-based images are smaller and standard for production
|
|
- Alternatives: `node:24.15.0-slim` (larger), `node:24.15.0` (full, much larger)
|
|
|
|
### Research Output: research.md
|
|
|
|
```markdown
|
|
# Research: Node.js v24.15.0 Upgrade
|
|
|
|
## Breaking Changes Assessment
|
|
|
|
Node.js v24 มี breaking changes หลักๆ ดังนี้:
|
|
1. **Permission Model**: Experimental permission model changes (ไม่กระทบ DMS)
|
|
2. **Buffer**: `Buffer()` constructor deprecation warnings (check codebase)
|
|
3. **Crypto**: Some crypto algorithm deprecations (verify hash usage)
|
|
4. **URL**: `url.parse()` further deprecated (เราใช้ new URL() อยู่แล้ว)
|
|
|
|
## Native Dependencies Status
|
|
|
|
| Package | Node v24 Support | Notes |
|
|
|---------|------------------|-------|
|
|
| bcrypt | ✅ v5.1.1+ | Uses N-API v8 |
|
|
| sharp | ✅ v0.33.0+ | Prebuilt binaries available |
|
|
| sqlite3 | ✅ v5.1.6+ | Uses node-gyp |
|
|
| argon2 | ✅ v0.40.0+ | N-API based |
|
|
|
|
## Docker Image
|
|
|
|
- `node:24.15.0-alpine3.21` - 190MB (compressed)
|
|
- ใช้ Alpine 3.21 (latest stable)
|
|
- มี `libc6-compat` สำหรับ native modules
|
|
|
|
## CI/CD Impact
|
|
|
|
- Gitea Actions runner รองรับ Node.js v24 ผ่าน `actions/setup-node`
|
|
- ไม่ต้องแก้ไข workflow structure มาก
|
|
- แค่เปลี่ยน node-version parameter
|
|
```
|
|
|
|
## Phase 1: Design & Contracts
|
|
|
|
### Data Model
|
|
|
|
**N/A** - Infrastructure upgrade does not modify data models.
|
|
|
|
No `data-model.md` required for this feature.
|
|
|
|
### API Contracts
|
|
|
|
**N/A** - No API changes.
|
|
|
|
No `contracts/` directory required for this feature.
|
|
|
|
### Quickstart Guide
|
|
|
|
Output: `quickstart.md`
|
|
|
|
```markdown
|
|
# Quick Start: Node.js v24.15.0 Upgrade
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js v24.15.0 installed locally (via nvm: `nvm install 24.15.0`)
|
|
- pnpm 9.x (`npm i -g pnpm@9`)
|
|
- Docker Desktop (for testing container builds)
|
|
|
|
## Local Development Upgrade
|
|
|
|
### 1. อัพเดท Node.js เวอร์ชัน
|
|
|
|
```bash
|
|
# ใช้ nvm (recommended)
|
|
nvm install 24.15.0
|
|
nvm use 24.15.0
|
|
node --version # ตรวจสอบ v24.15.0
|
|
|
|
# หรือดาวน์โหลดจาก nodejs.org โดยตรง
|
|
```
|
|
|
|
### 2. รีเจนเนอเรท lockfile
|
|
|
|
```bash
|
|
# Backend
|
|
cd backend
|
|
rm -rf node_modules pnpm-lock.yaml
|
|
pnpm install
|
|
|
|
# Frontend
|
|
cd frontend
|
|
rm -rf node_modules pnpm-lock.yaml
|
|
pnpm install
|
|
```
|
|
|
|
### 3. รันเทสต์
|
|
|
|
```bash
|
|
# Backend
|
|
cd backend
|
|
pnpm test
|
|
|
|
# Frontend
|
|
cd frontend
|
|
pnpm test
|
|
```
|
|
|
|
### 4. Build Docker Images
|
|
|
|
```bash
|
|
# Backend
|
|
cd backend
|
|
docker build -t nap-dms-backend:v24-test .
|
|
|
|
# Frontend
|
|
cd frontend
|
|
docker build -t nap-dms-frontend:v24-test .
|
|
```
|
|
|
|
## Rollback Procedure
|
|
|
|
หากพบปัญหาใน production:
|
|
|
|
```bash
|
|
# 1. Revert Dockerfile กลับไป node:22.20.0-alpine
|
|
# 2. Revert package.json engines field
|
|
# 3. Revert .nvmrc
|
|
# 4. Rebuild และ redeploy
|
|
|
|
# ใช้ git revert:
|
|
git revert HEAD # ถ้า upgrade เป็น commit ล่าสุด
|
|
# หรือ
|
|
.git checkout main -- backend/Dockerfile frontend/Dockerfile
|
|
```
|
|
|
|
## Verification Checklist
|
|
|
|
- [ ] `node --version` แสดง v24.15.0
|
|
- [ ] Backend start ได้ไม่มี error
|
|
- [ ] Frontend build สำเร็จ
|
|
- [ ] 100% tests pass
|
|
- [ ] Docker build สำเร็จทั้ง backend และ frontend
|
|
```
|
|
|
|
## Complexity Tracking
|
|
|
|
**No complexity violations** - This is a straightforward infrastructure upgrade within existing project structure.
|
|
|
|
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
|
|-----------|------------|--------------------------------------|
|
|
| N/A | - | - |
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 1: Preparation
|
|
1. Create feature branch `103-node-upgrade`
|
|
2. Update `.nvmrc` files (backend/, frontend/)
|
|
3. Update `package.json` engines fields
|
|
4. Update Dockerfiles base images
|
|
|
|
### Phase 2: CI/CD Updates
|
|
1. Update `.gitea/workflows/ci-deploy.yml` node-version
|
|
2. Test CI pipeline on feature branch
|
|
|
|
### Phase 3: Local Validation
|
|
1. Regenerate pnpm-lock.yaml files
|
|
2. Run full test suites
|
|
3. Verify native dependencies compile
|
|
|
|
### Phase 4: Staging Deployment
|
|
1. Deploy to staging environment
|
|
2. Run integration tests
|
|
3. Performance baseline comparison
|
|
|
|
### Phase 5: Production Rollout
|
|
1. Schedule maintenance window
|
|
2. Deploy with blue-green strategy
|
|
3. Monitor for 24 hours
|
|
4. Document any issues
|
|
|
|
## Risks & Mitigations
|
|
|
|
| Risk | Likelihood | Impact | Mitigation |
|
|
|------|------------|--------|------------|
|
|
| Native deps fail to compile | Medium | High | Test all native deps in staging; keep rollback ready |
|
|
| Performance regression | Low | Medium | Benchmark before/after; 5% threshold for rollback |
|
|
| CI/CD breakage | Low | Medium | Test CI on feature branch first |
|
|
| Developer workstation issues | Medium | Low | Document nvm upgrade steps; provide support |
|
|
|
|
## Success Validation
|
|
|
|
- ✅ All tests pass (Jest/Vitest)
|
|
- ✅ Docker builds succeed
|
|
- ✅ CI/CD pipelines green
|
|
- ✅ Staging environment stable 24 hours
|
|
- ✅ Performance within 5% baseline
|
|
- ✅ Rollback tested and documented
|