ht-docker-node/readme.md

# 🐳 ht-docker-node

> Production-ready Docker images for Node.js development with multi-architecture support, modern runtimes, and intelligent version management.

**Multi-arch ready** • **Alpine & Ubuntu** • **NVM built-in** • **Bun, Deno & pnpm** • **CI/CD optimized**

---

## 🚀 Quick Start

```bash
# Pull and run the latest Node.js LTS image
docker pull registry.gitlab.com/hosttoday/ht-docker-node:latest
docker run -it registry.gitlab.com/hosttoday/ht-docker-node:latest

# Or use Alpine for smaller images (200MB vs 800MB+)
docker pull registry.gitlab.com/hosttoday/ht-docker-node:alpine-node
```

## 📦 Available Images

### Ubuntu-Based Images (Full-Featured)

Perfect for complex builds requiring native dependencies and maximum compatibility.

| Tag | Description | Use Case |
|-----|-------------|----------|
| `:latest` / `:lts` | Node.js LTS with NVM | General purpose, production builds |
| `:stable` | Node.js stable release | Latest stable features |
| `:npmci` | With npmci preinstalled | CI/CD pipelines |
| `:npmts` | npmci + npmts | TypeScript projects |
| `:npmpage` | npmci + npmts + npmpage | Static site generation |
| `:mongo` | npmci + npmts + MongoDB | Full-stack development |

### Alpine-Based Images (Lightweight & Multi-Arch) ⚡

**40-60% smaller** than Ubuntu images. Native performance on **both x64 and ARM64** (Apple Silicon, ARM servers).

| Tag | Description | Size | Architectures |
|-----|-------------|------|---------------|
| `:alpine-node` | Node.js LTS + NVM + pnpm | ~200MB | amd64, arm64 |
| `:alpine-deno` | Node.js LTS + NVM + Deno | ~180MB | amd64, arm64 |
| `:alpine-bun` | Node.js LTS + NVM + Bun | ~150MB | amd64, arm64 |

**✨ Multi-architecture magic:** Docker automatically selects the right image for your platform. Build on Mac, deploy on Linux servers—same Dockerfile, native speed everywhere.

> **Note:** The Deno image uses Alpine edge to access the official musl-compiled Deno package from Alpine's community repository.

---

## 💡 Key Features

### 🔄 NVM (Node Version Manager) Built-In

Switch Node.js versions **instantly** without rebuilding images:

```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:latest

# Works directly in RUN commands - no sourcing needed!
RUN nvm install 18.20.0
RUN nvm use 18 && npm install
RUN nvm install 20 && nvm use 20 && npm test

# Set default for subsequent commands
RUN nvm install 19 && nvm alias default 19
```

### 🎯 CI/CD Workflow Ready

NVM works seamlessly in GitHub Actions, GitLab CI, and other automation:

```yaml
# .gitlab-ci.yml
test:
  image: registry.gitlab.com/hosttoday/ht-docker-node:latest
  script:
    - nvm install 18
    - nvm use 18
    - npm ci
    - npm test

    # Test on multiple Node versions
    - nvm install 20
    - nvm use 20
    - npm test
```

### 🏔️ Alpine: Production-Optimized

```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node

# Same NVM commands as Ubuntu
RUN nvm install 20 && nvm use 20
RUN pnpm install
RUN pnpm build

# Result: 200MB image vs 800MB+ Ubuntu
```

**Why Alpine?**
- ✅ **60-75% smaller images** → Faster deployments
- ✅ **Reduced attack surface** → Better security
- ✅ **Native musl builds** → No glibc compatibility issues
- ✅ **Multi-arch support** → One image, all platforms

---

## 🛠️ Usage Examples

### Basic Node.js Application

```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node

WORKDIR /app

# NVM is already configured, Node.js LTS is ready
COPY package*.json ./
RUN pnpm install

COPY . .
RUN pnpm build

EXPOSE 3000
CMD ["node", "dist/index.js"]
```

### Multi-Version Testing

```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:latest

WORKDIR /app
COPY package*.json ./

# Test on Node 18
RUN nvm install 18 && nvm use 18 && npm ci && npm test

# Test on Node 20
RUN nvm install 20 && nvm use 20 && npm ci && npm test

# Use Node 20 for production build
RUN nvm alias default 20 && npm run build
```

### Deno Application

```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-deno

WORKDIR /app

# Both Deno and Node.js are available
COPY . .

# Use Deno for the app
CMD ["deno", "run", "--allow-net", "main.ts"]

# Or switch to Node.js if needed
# RUN nvm use default && npm install
```

### Bun for Ultra-Fast Builds

```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-bun

WORKDIR /app

# Bun is 10-20x faster for package installation
COPY package.json bun.lockb ./
RUN bun install

COPY . .
RUN bun run build

# Node.js also available via NVM
CMD ["bun", "run", "start"]
```

### TypeScript Project with Multi-Stage Build

```dockerfile
# Build stage
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node AS builder

WORKDIR /app
COPY package*.json ./
RUN pnpm install

COPY tsconfig.json ./
COPY src ./src
RUN pnpm build

# Production stage
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node

WORKDIR /app
COPY package*.json ./
RUN pnpm install --prod

COPY --from=builder /app/dist ./dist

EXPOSE 3000
CMD ["node", "dist/index.js"]
```

---

## 🔧 NVM Usage Patterns

### In Dockerfiles

```dockerfile
# Install specific version
RUN nvm install 18.20.0

# Use version
RUN nvm use 18

# Set default (persists across RUN commands)
RUN nvm alias default 18

# Chain commands in single RUN
RUN nvm install 19 && nvm use 19 && npm install
```

### In CI/CD Scripts

```bash
#!/bin/bash
# NVM is automatically available in bash scripts

nvm install 20
nvm use 20
npm ci
npm test
```

### Version Switching

```bash
# List installed versions
nvm ls

# Install and switch to latest LTS
nvm install --lts
nvm use --lts

# Install specific version
nvm install 18.20.0

# Use installed version
nvm use 18
```

---

## 🏗️ Building Multi-Architecture Images

For teams building custom images:

```bash
# Clone the repo
git clone https://github.com/HostToday/ht-docker-node.git
cd ht-docker-node

# Build Alpine images (native platform for local testing)
chmod +x build-alpine-images.sh
./build-alpine-images.sh

# Test the built images
chmod +x test-alpine-images.sh
./test-alpine-images.sh
```

### Production Multi-Arch Builds

For publishing to registries:

```bash
# Build for both amd64 and arm64, push to registry
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -f Dockerfile_alpine_node \
  -t your-registry/your-image:alpine-node \
  --push \
  .
```

---

## 📚 Advanced Examples

### Docker Compose Setup

```yaml
version: '3.8'

services:
  app:
    image: registry.gitlab.com/hosttoday/ht-docker-node:alpine-node
    working_dir: /app
    volumes:
      - .:/app
      - /app/node_modules
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=development
    command: sh -c "pnpm install && pnpm dev"

  mongo:
    image: mongo:latest
    ports:
      - "27017:27017"
```

### GitHub Actions Workflow

```yaml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: registry.gitlab.com/hosttoday/ht-docker-node:alpine-node

    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: pnpm install

      - name: Run tests
        run: pnpm test

      - name: Test on multiple Node versions
        run: |
          for version in 18 20; do
            echo "Testing on Node $version"
            nvm install $version
            nvm use $version
            pnpm test
          done
```

### Custom Base Image

```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node

# Add your custom tools
RUN apk add --no-cache \
    python3 \
    make \
    g++ \
    postgresql-client

# Configure your environment
ENV DATABASE_URL="postgresql://localhost/mydb"

# Your app setup
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN pnpm install

COPY . .
CMD ["pnpm", "start"]
```

---

## 🎓 Best Practices

### ✅ DO

- **Use Alpine images for production** (smaller, more secure)
- **Pin Node versions in production** (`nvm alias default 20.11.0`)
- **Use multi-stage builds** to reduce final image size
- **Leverage build cache** with proper COPY order
- **Run as non-root user** in production

### ❌ DON'T

- Don't use `:latest` tag in production (be explicit)
- Don't install packages globally if local works
- Don't copy `node_modules` (let the build install them)
- Don't skip `.dockerignore` (keeps builds fast)

### 🔒 Security Tips

```dockerfile
# Example: Production-hardened Dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node

# Create non-root user
RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001

WORKDIR /app

# Install deps as root
COPY package*.json ./
RUN pnpm install --frozen-lockfile && pnpm cache clean

# Copy source
COPY --chown=nodejs:nodejs . .

# Build
RUN pnpm build

# Switch to non-root user
USER nodejs

EXPOSE 3000
CMD ["node", "dist/index.js"]
```

---

## 🐛 Troubleshooting

### NVM command not found

If NVM isn't available in your script:

```bash
# Manually source NVM (shouldn't be needed in our images)
export NVM_DIR="/usr/local/nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
```

### Alpine native module build failures

Some npm packages need build tools:

```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node

# Install build dependencies
RUN apk add --no-cache python3 make g++

# Now install your packages
RUN pnpm install
```

### Permission denied errors

```dockerfile
# Fix ownership before switching users
COPY --chown=node:node . .
USER node
```

---

## 📊 Image Comparison

| Feature | Ubuntu `:latest` | Alpine `:alpine-node` |
|---------|------------------|----------------------|
| Base Size | ~800MB | ~200MB |
| Build Tools | ✅ Full | ⚠️ Install separately |
| Compatibility | ✅ Maximum | ✅ Good (musl) |
| Multi-arch | ❌ amd64 only | ✅ amd64, arm64 |
| Security | ✅ Good | ✅ Excellent (smaller surface) |
| Speed | Fast | Faster (smaller) |
| Use Case | Complex builds | Production, CI/CD |

---

## 🔗 Useful Links

- **GitHub Repository:** https://github.com/HostToday/ht-docker-node
- **Docker Hub:** registry.gitlab.com/hosttoday/ht-docker-node
- **NVM Documentation:** https://github.com/nvm-sh/nvm
- **Alpine Linux:** https://alpinelinux.org/
- **Node.js Unofficial Builds:** https://unofficial-builds.nodejs.org/ (musl support)

---

## 📋 Changelog

See [changelog.md](changelog.md) for detailed version history.

**Latest Updates (v5.0.148):**
- ✨ Multi-architecture Alpine images (amd64 + arm64)
- ✨ Native Deno support via Alpine edge
- ✨ Bun runtime integration
- ✨ Simplified image tags (`:alpine-node` vs `:alpine-x64-node`)
- 🚀 docker buildx integration for cross-platform builds
- 📦 pnpm preinstalled on Alpine Node image
- 🔧 NVM 0.40.1 with improved Alpine/musl support

---

## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.