ht-docker-node/readme.hints.md

Technical Implementation Notes

NVM Support (v5.0.147)

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 v20.12.2
• 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 86 in Dockerfile

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

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

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