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:

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

**Workaround**: Chain commands or set default:

```dockerfile
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:
```bash
docker run --entrypoint /bin/bash image -c "commands"
```