# 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:

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:

# .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

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

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

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

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

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

# 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

# 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

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

nvm install 20
nvm use 20
npm ci
npm test

Version Switching

# 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:

# 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:

# 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

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

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

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

# 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:

# 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:

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

# 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 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 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.

readme.md

🐳 ht-docker-node

🚀 Quick Start