Skip to content

DOCKER-002: Upgrade Node.js from 23 to 24 LTS

Background

This fix upgrades the Node.js base images in our Dockerfiles from version 23 to version 24 LTS ("Krypton"). Node.js 23 is a "Current" release with a shorter support cycle, while Node.js 24 is the active Long-Term Support (LTS) version with extended maintenance until April 2027.

The upgrade ensures better long-term stability, production readiness, and aligns with Node.js best practices for enterprise deployments.

Changes

Modified Files:

  • Dockerfile: Updated both Node.js build stage and runtime stage
  • Line 27: FROM node:23-slim AS node-builderFROM node:24-slim AS node-builder
  • Line 35: FROM node:23-slimFROM node:24-slim
  • Dockerfile.lite: Updated base image
  • Line 2: FROM node:23-slimFROM node:24-slim

Key Differences:

Aspect Node.js 23 Node.js 24 LTS
Release Type Current Long-Term Support
Support Until June 2025 April 2027
Production Ready Yes Yes (Preferred)
V8 Engine 13.0+ 13.6
Active LTS Phase N/A Until October 2025

Testing

Compatibility Verification

All critical dependencies verified as Node.js 24 compatible:

npm view express engines.node
# Output: >= 18

npm view openai engines.node  
# Output: 20.x || 22.x || 23.x || 24.x || 25.x

npm view better-sqlite3 engines.node
# No engine restrictions

npm view axios engines.node
# Output: >= 12

Build Testing

# Test main Dockerfile build
docker build -t paperless-ai-next:test .

# Test lite version build
docker build -f Dockerfile.lite -t paperless-ai-next:lite-test .

# Verify Node.js version in images
docker run --rm paperless-ai-next:test node --version
# Expected output: v24.x.x

# Run basic functionality test
docker run --rm -e PAPERLESS_AI_PORT=3000 paperless-ai-next:test npm --version

Runtime Verification

# Start container and check health
docker-compose up -d
docker-compose logs -f

# Verify no compatibility errors in logs
# Test document processing workflow
# Confirm AI services work correctly

Impact

Benefits:

  • Extended Support: Maintenance until April 2027 (vs June 2025)
  • Production Stability: LTS branch receives more testing and bugfixes
  • Security Updates: Longer security patch window
  • V8 13.6: Latest stable JavaScript engine features
  • Explicit Compatibility: OpenAI SDK officially supports Node.js 24

Performance:

  • No significant performance differences expected
  • V8 13.6 includes minor optimizations
  • Same npm version (11.6.2)

Breaking Changes:

  • None affecting our codebase: All SEMVER-MAJOR changes in Node.js 24 are internal V8/C++ API updates
  • No code modifications needed: Pure infrastructure upgrade
  • Backward Compatible: All Express/Node.js APIs remain stable

Rollback Plan

If issues arise (unlikely), rollback is simple:

git revert e6b9820  # Revert commit hash
docker-compose build --no-cache
docker-compose up -d

Or manually edit Dockerfiles: - Change FROM node:24-slim back to FROM node:23-slim

Upstream Status

  • Not applicable (infrastructure maintenance)
  • This is a proactive maintenance upgrade
  • Follows Node.js release schedule best practices

References

Integration Date

  1. Dezember 2025
  • Improves long-term maintainability
  • Aligns with Docker best practices for LTS base images
  • Complements DOCKER-001 optimization efforts