ht-docker-node/readme.hints.md

Technical Implementation Notes

NVM Support (v5.2.0)

How NVM Works in This Image

The image provides full nvm support in three contexts:

1. Dockerfile RUN commands: Via /usr/local/bin/bash-with-nvm wrapper
2. CI/CD workflow scripts: Via /etc/bash.bashrc prepended configuration
3. Interactive shells: Via /etc/bash.bashrc standard loading

Key Components

1. /etc/bash.bashrc (Prepended NVM Init)

• NVM initialization is prepended to /etc/bash.bashrc
• Critical: Placed BEFORE the [ -z "$PS1" ] && return line
• This ensures nvm loads in both interactive AND non-interactive bash shells
• Location: Lines 1-3 of /etc/bash.bashrc

2. /usr/local/bin/bash-with-nvm (Build-Time Wrapper)

• Wrapper script that sources nvm before executing Dockerfile RUN commands
• Used via SHELL ["/usr/local/bin/bash-with-nvm"] directive
• Ensures nvm is available during docker build without manual sourcing

3. /usr/local/bin/docker-entrypoint.sh (Runtime Wrapper)

• ENTRYPOINT that detects bash -c commands
• Automatically injects source /etc/bash.bashrc for bash -c invocations
• Passes through other commands unchanged
• Critical for CI/CD workflow support

4. ENV PATH Fallback

• Maintains ENV PATH pointing to default Node v24.13.0
• Ensures non-bash shells (sh, dash) still have node access
• Backward compatible with existing usage

Why This Approach Works

Problem: nvm is a shell function, not a binary

• Can't be found in PATH
• Must be sourced into each shell session
• Docker's /bin/sh doesn't support bash functions

Solution Strategy:

1. Prepend nvm init to /etc/bash.bashrc (before early return)
2. Use wrapper for build-time (SHELL directive)
3. Use ENTRYPOINT for runtime (docker run / CI/CD)
4. Keep ENV PATH for fallback

Version Persistence Limitation

Each Dockerfile RUN command creates a new shell:

RUN nvm install 18      # Installs but doesn't persist
RUN node --version      # Shows v20.12.2 (ENV PATH)

Workaround: Chain commands or set default:

RUN nvm install 18 && nvm alias default 18
RUN node --version      # Now shows v18.x.x

Testing Performed

• ✅ Dockerfile RUN: nvm install, nvm use, version switching
• ✅ Runtime bash -c: All nvm commands work
• ✅ CI/CD workflows: Tested in .gitea/workflows context
• ✅ Backward compat: pnpm, npmci, ENV PATH fallback
• ✅ Multi-stage builds: nvm available in all stages
• ✅ Interactive shells: Full nvm access

Maintenance Notes

If updating nvm version: Modify line 87 in Dockerfile (currently NVM v0.40.1)

If base image changes: Verify /etc/bash.bashrc structure still has early return pattern

Ubuntu 24.04 Upgrade Notes

• Base image upgraded from Ubuntu 20.04 to 24.04
• Python 2 removed (EOL since 2020), Python 3 retained
• Package changes for 24.04 compatibility:
  • gconf-service and libgconf-2-4 removed (deprecated GConf)
  • libgcc1 replaced with libgcc-s1
  • libappindicator1 replaced with libayatana-appindicator3-1
  • libasound2 replaced with libasound2t64 (t64 transition)
  • libgbm1 and libatk-bridge2.0-0 added for Chrome/Puppeteer
• MongoDB upgraded from 4.4 to 8.0 (uses modern gpg keyring approach instead of deprecated apt-key)
• Node.js upgraded to v24.13.0 LTS (Krypton, supported until April 2028)

If ENTRYPOINT conflicts: Users can override with --entrypoint flag:

docker run --entrypoint /bin/bash image -c "commands"