host.today/ht-docker-node
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docker): Rework Dockerfile into layered installs and add tooling (tini, chromium, MongoDB); simplify Alpine CI image Python/pip setup; add tsdocker devDependency; remove npmextra push flag; update README and registry links

Browse Source
This commit is contained in:
Jürgen Kunz
2026-02-07 10:43:46 +00:00
parent 6935d292b4
commit cb0bf61a6b
7 changed files with 3419 additions and 351 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
Dockerfile
View File

@@ -9,12 +9,11 @@ ENV NODE_VERSION_LTS="24.13.0" NODE_VERSION_STABLE="24.13.0" NVM_DIR="/usr/local
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
ENV CHROME_BIN=/usr/bin/chromium-browser ENV CHROME_BIN=/usr/bin/chromium-browser
# Set debconf to run non-interactively and install packages # Layer 1: Base system + dev tools
RUN echo 'debconf debconf/frontend select Noninteractive' | debconf-set-selections \ RUN echo 'debconf debconf/frontend select Noninteractive' | debconf-set-selections \
&& apt-get update \ && apt-get update \
&& apt-get upgrade --no-install-recommends -y \ && apt-get upgrade --no-install-recommends -y \
&& apt-get install -y -q --no-install-recommends \ && apt-get install -y -q --no-install-recommends \
# base libs
software-properties-common \ software-properties-common \
apt-transport-https \ apt-transport-https \
build-essential \ build-essential \
@@ -31,7 +30,13 @@ RUN echo 'debconf debconf/frontend select Noninteractive' | debconf-set-selectio
ssh \ ssh \
wget \ wget \
unzip \ unzip \
# puppeteer iputils-ping \
dnsutils \
tini
# Layer 2: Chromium + Puppeteer/Playwright browser deps
RUN apt-get install -y -q --no-install-recommends \
chromium-browser \
libasound2t64 \ libasound2t64 \
libatk1.0-0 \ libatk1.0-0 \
libatk-bridge2.0-0 \ libatk-bridge2.0-0 \
@@ -63,30 +68,21 @@ RUN echo 'debconf debconf/frontend select Noninteractive' | debconf-set-selectio
libxrender1 \ libxrender1 \
libxss1 \ libxss1 \
libxtst6 \ libxtst6 \
ca-certificates \
fonts-liberation \ fonts-liberation \
libayatana-appindicator3-1 \ libayatana-appindicator3-1 \
libnss3 \ libnss3 \
lsb-release \ lsb-release \
xdg-utils \ xdg-utils
# network
iputils-ping \
dnsutils \
# init
tini \
# chromium (multi-arch compatible - works on both amd64 and arm64) # Layer 3: MongoDB 8.0
&& apt-get install -y -q --no-install-recommends chromium-browser \ RUN curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | \
# mongodb 8.0
&& curl -fsSL https://www.mongodb.org/static/pgp/server-8.0.asc | \
gpg --dearmor -o /usr/share/keyrings/mongodb-server-8.0.gpg \ gpg --dearmor -o /usr/share/keyrings/mongodb-server-8.0.gpg \
&& echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/8.0 multiverse" | \ && echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-8.0.gpg ] https://repo.mongodb.org/apt/ubuntu noble/mongodb-org/8.0 multiverse" | \
tee /etc/apt/sources.list.d/mongodb-org-8.0.list \ tee /etc/apt/sources.list.d/mongodb-org-8.0.list \
&& apt-get update \ && apt-get update \
&& apt-get install -y -q --no-install-recommends mongodb-org \ && apt-get install -y -q --no-install-recommends mongodb-org \
&& apt-get clean \ && apt-get clean \
&& rm -r /var/lib/apt/lists/* && rm -rf /var/lib/apt/lists/*
# Install nvm with node and npm # Install nvm with node and npm
RUN mkdir -p $NVM_DIR && curl https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash RUN mkdir -p $NVM_DIR && curl https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

4
Dockerfile_alpine-szci
View File

@@ -1,9 +1,7 @@
FROM host.today/ht-docker-node:alpine-node FROM host.today/ht-docker-node:alpine-node
RUN apk update && apk add bash libc6-compat alpine-sdk RUN apk update && apk add bash libc6-compat alpine-sdk
ENV PYTHONUNBUFFERED=1 ENV PYTHONUNBUFFERED=1
RUN apk add --update --no-cache python3 && ln -sf python3 /usr/bin/python RUN apk add --update --no-cache python3 py3-pip && ln -sf python3 /usr/bin/python
RUN python3 -m ensurepip
RUN pip3 install --no-cache --upgrade pip setuptools
RUN apk add --update alpine-sdk && \ RUN apk add --update alpine-sdk && \
apk add libffi-dev openssl-dev && \ apk add libffi-dev openssl-dev && \
apk add python3-dev && \ apk add python3-dev && \

10
changelog.md
View File

@@ -1,5 +1,15 @@
# Changelog # Changelog
## 2026-02-07 - 5.5.0 - feat(docker)
Rework Dockerfile into layered installs and add tooling (tini, chromium, MongoDB); simplify Alpine CI image Python/pip setup; add tsdocker devDependency; remove npmextra push flag; update README and registry links
- Dockerfile: split apt installs into logical layers, added tini, iputils-ping and dnsutils, moved chromium-browser into its own layer, and fixed apt cache cleanup (rm -rf)
- Dockerfile: add MongoDB 8.0 apt repository and install in a dedicated layer
- Alpine image (Dockerfile_alpine-szci): consolidated python3 and py3-pip install (removed ensurepip + manual pip upgrade)
- package.json: add devDependency @git.zone/tsdocker@^1.15.1
- npmextra.json: removed "push": false flag (affects CI/publish behavior)
- README: update registry URLs to code.foss.global, document tini and NVM behavior, refresh image descriptions and links
## 2026-02-06 - 5.4.0 - feat(ci) ## 2026-02-06 - 5.4.0 - feat(ci)
replace npmci with szci across CI and images; add szci preinstalled images and make tini the PID 1 init in Docker images replace npmci with szci across CI and images; add szci preinstalled images and make tini the PID 1 init in Docker images

1
npmextra.json
View File

@@ -40,7 +40,6 @@
"docker.io": "hosttoday/ht-docker-node" "docker.io": "hosttoday/ht-docker-node"
}, },
"platforms": ["linux/amd64", "linux/arm64"], "platforms": ["linux/amd64", "linux/arm64"],
"push": false,
"testDir": "./test" "testDir": "./test"
}, },
"tsdoc": { "tsdoc": {

5
package.json
View File

@@ -33,5 +33,8 @@
"szci", "szci",
"node version management", "node version management",
"typescript" "typescript"
] ],
"devDependencies": {
"@git.zone/tsdocker": "^1.15.1"
}
} }

3177
pnpm-lock.yaml generated
View File

File diff suppressed because it is too large Load Diff

535
readme.md
View File

@@ -1,122 +1,163 @@
# 🐳 ht-docker-node # 🐳 ht-docker-node
> Production-ready Docker images for Node.js development with multi-architecture support, modern runtimes, and intelligent version management. > Production-ready Docker images for Node.js with NVM built in, multi-arch support, and modern runtimes (Bun, Deno). Every image ships with **tini** as PID 1 and full **NVM** integration — switch Node versions on the fly, no sourcing required.
**Multi-arch ready** • **Alpine & Ubuntu** • **NVM built-in** • **Bun, Deno & pnpm** • **CI/CD optimized** **Multi-arch** • **Alpine & Ubuntu** • **NVM built-in** • **Bun, Deno & pnpm** • **tini init** • **CI/CD optimized**
## Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
--- ---
## 🚀 Quick Start ## 🚀 Quick Start
```bash ```bash
# Pull and run the latest Node.js LTS image # Pull and run the full-featured Ubuntu image
docker pull registry.gitlab.com/hosttoday/ht-docker-node:latest docker pull code.foss.global/host.today/ht-docker-node:latest
docker run -it registry.gitlab.com/hosttoday/ht-docker-node:latest docker run -it code.foss.global/host.today/ht-docker-node:latest
# Or use Alpine for smaller images (200MB vs 800MB+) # Or go lean with Alpine (~200 MB vs ~900 MB)
docker pull registry.gitlab.com/hosttoday/ht-docker-node:alpine-node docker pull code.foss.global/host.today/ht-docker-node:alpine-node
docker run -it code.foss.global/host.today/ht-docker-node:alpine-node
``` ```
NVM is ready the moment you enter the container — no manual sourcing, no `.bashrc` hacks:
```bash
$ nvm install 22
$ nvm use 22
$ node -v # v22.x.x ✅
```
---
## 📦 Available Images ## 📦 Available Images
### Ubuntu-Based Images (Full-Featured) ### Ubuntu-Based (Full-Featured)
Perfect for complex builds requiring native dependencies and maximum compatibility. Built on **Ubuntu 24.04**. Maximum compatibility, all build tools included, plus Chromium for Puppeteer/Playwright, and MongoDB 8.0.
| Tag | Description | Use Case | | Tag | Description | Key Contents |
|-----|-------------|----------| |-----|-------------|--------------|
| `:latest` | Node.js LTS with NVM (Ubuntu 24.04) | General purpose, production builds | | `:latest` | Kitchen-sink Node.js image | Node LTS + NVM + pnpm + Bun + Deno + Chromium + MongoDB 8.0 |
| `:lts` | Based on latest | Explicit LTS naming | | `:lts` | Alias of `:latest` | Same — explicit LTS naming for clarity |
| `:szci` | With szci preinstalled | CI/CD pipelines | | `:szci` | CI/CD workhorse | `:latest` + `@ship.zone/szci` preinstalled |
| `:fossglobal_preinstalled_<ver>` | Preloaded tooling image | `:szci` + tsrun, tstest, tapbundle, smartfile, and more |
> **All images include [tini](https://github.com/krallin/tini) as PID 1 init**, ensuring proper signal forwarding and zombie process reaping out of the box. ### Alpine-Based (Lightweight & Multi-Arch) ⚡
### Alpine-Based Images (Lightweight & Multi-Arch) ⚡ **40–75 % smaller** than Ubuntu. Native performance on **both amd64 and arm64** (Apple Silicon, Graviton, Ampere).
**40-60% smaller** than Ubuntu images. Native performance on **both x64 and ARM64** (Apple Silicon, ARM servers).
| Tag | Description | Size | Architectures | | Tag | Description | Size | Architectures |
|-----|-------------|------|---------------| |-----|-------------|------|---------------|
| `:alpine-node` | Node.js LTS + NVM + pnpm | ~200 MB | amd64, arm64 | | `:alpine-node` | Node.js LTS + NVM + pnpm | ~200 MB | amd64, arm64 |
| `:alpine-deno` | Node.js LTS + NVM + Deno | ~180MB | amd64, arm64 |
| `:alpine-bun` | Node.js LTS + NVM + Bun | ~150 MB | amd64, arm64 | | `:alpine-bun` | Node.js LTS + NVM + Bun | ~150 MB | amd64, arm64 |
| `:alpine-deno` | Node.js LTS + NVM + Deno | ~180 MB | amd64, arm64 |
| `:alpine-szci` | Alpine Node + szci + build tools | ~250 MB | amd64, arm64 | | `:alpine-szci` | Alpine Node + szci + build tools | ~250 MB | 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. > 💡 Docker automatically pulls the right arch for your platform. Build on a Mac, deploy on an ARM server — same tag, native speed everywhere.
> **Note:** The Deno image uses Alpine edge to access the official musl-compiled Deno package from Alpine's community repository. > **Note:** The Deno Alpine image uses `alpine:edge` to get the official musl-compiled Deno from the community repository.
### What every image includes
| Feature | Detail |
|---------|--------|
| **tini** | PID 1 init — proper signal forwarding & zombie reaping |
| **NVM** | v0.40.1 — works in `RUN`, `docker exec`, CI scripts, interactive shells |
| **Node.js** | LTS v24.13.0 (default, switchable) |
| **docker-entrypoint.sh** | Loads NVM at runtime so `docker run … bash -c "nvm use 22"` just works |
--- ---
## 💡 Key Features ## 💡 Key Features
### 🔄 NVM (Node Version Manager) Built-In ### 🔄 NVM — Zero-Config Node Version Management
Switch Node.js versions **instantly** without rebuilding images: NVM is pre-wired into every shell context. No manual sourcing required in any of these scenarios:
**Dockerfile RUN commands** (via the `bash-with-nvm` SHELL wrapper):
```dockerfile ```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:latest FROM code.foss.global/host.today/ht-docker-node:latest
# Works directly in RUN commands - no sourcing needed! # Works directly — no sourcing needed!
RUN nvm install 18.20.0 RUN nvm install 22 && nvm use 22 && npm ci
RUN nvm use 18 && npm install RUN nvm alias default 22 # persists for later RUN steps
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 **CI/CD scripts** (via `BASH_ENV=/etc/bash.bashrc`):
NVM works seamlessly in GitHub Actions, GitLab CI, and other automation:
```yaml ```yaml
# .gitlab-ci.yml # Gitea / GitLab CI
test: test:
image: registry.gitlab.com/hosttoday/ht-docker-node:latest image: code.foss.global/host.today/ht-docker-node:latest
script: script:
- nvm install 18 - nvm install 22 && nvm use 22
- nvm use 18 - pnpm ci && pnpm test
- npm ci
- npm test
# Test on multiple Node versions
- nvm install 20
- nvm use 20
- npm test
``` ```
### 🏔️ Alpine: Production-Optimized **Interactive shells** and **`docker exec`**:
```bash
docker exec -it mycontainer bash
$ nvm ls # lists installed versions
$ nvm install 20 # installs Node 20
$ nvm use 20 # switches immediately
```
> ⚠️ **Note on version persistence across RUN steps:** Each Dockerfile `RUN` starts a new shell. Use `nvm alias default <version>` to persist your choice, or chain commands in a single `RUN`.
### 🛡️ tini — Proper Init for Containers
All images use [tini](https://github.com/krallin/tini) as PID 1:
```
tini → docker-entrypoint.sh → your command
```
This means:
- ✅ Signals (SIGTERM, SIGINT) are forwarded correctly to your app
- ✅ Zombie processes are reaped automatically
- ✅ Clean container shutdown — no orphaned processes
### 🌐 Chromium (Ubuntu `:latest` only)
Puppeteer and Playwright work out of the box:
```javascript
const browser = await puppeteer.launch(); // uses /usr/bin/chromium-browser
```
Environment variables `PUPPETEER_EXECUTABLE_PATH` and `CHROME_BIN` are pre-set. Multi-arch compatible (amd64 + arm64).
### 🏔️ Alpine — Production Optimized
```dockerfile ```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node FROM code.foss.global/host.today/ht-docker-node:alpine-node
# Same NVM commands as Ubuntu RUN nvm install 22 && nvm use 22
RUN nvm install 20 && nvm use 20 RUN pnpm install && pnpm build
RUN pnpm install # Result: ~200 MB image
RUN pnpm build
# Result: 200MB image vs 800MB+ Ubuntu
``` ```
**Why Alpine?** Why Alpine?
- ✅ **60-75% smaller images** → Faster deployments - ✅ **60–75 % smaller** → Faster pulls, faster deploys
- ✅ **Reduced attack surface** → Better security - ✅ **Reduced attack surface** → Fewer packages = fewer CVEs
- ✅ **Native musl builds** → No glibc compatibility issues - ✅ **Native musl builds** → No glibc compatibility layer
- ✅ **Multi-arch support** → One image, all platforms - ✅ **Multi-arch** → Same tag works on x64 and ARM64
--- ---
## 🛠️ Usage Examples ## 🛠️ Usage Examples
### Basic Node.js Application ### Basic Node.js App
```dockerfile ```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node FROM code.foss.global/host.today/ht-docker-node:alpine-node
WORKDIR /app WORKDIR /app
# NVM is already configured, Node.js LTS is ready
COPY package*.json ./ COPY package*.json ./
RUN pnpm install RUN pnpm install
@@ -130,135 +171,113 @@ CMD ["node", "dist/index.js"]
### Multi-Version Testing ### Multi-Version Testing
```dockerfile ```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:latest FROM code.foss.global/host.today/ht-docker-node:latest
WORKDIR /app WORKDIR /app
COPY package*.json ./ 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 RUN nvm install 20 && nvm use 20 && npm ci && npm test
RUN nvm install 22 && nvm use 22 && npm ci && npm test
# Use Node 20 for production build # Ship with Node 22
RUN nvm alias default 20 && npm run build RUN nvm alias default 22 && npm run build
``` ```
### Deno Application ### Deno Application
```dockerfile ```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-deno FROM code.foss.global/host.today/ht-docker-node:alpine-deno
WORKDIR /app WORKDIR /app
# Both Deno and Node.js are available
COPY . . COPY . .
# Use Deno for the app # Deno and Node.js are both available
CMD ["deno", "run", "--allow-net", "main.ts"] 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 ### Bun for Ultra-Fast Installs
```dockerfile ```dockerfile
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-bun FROM code.foss.global/host.today/ht-docker-node:alpine-bun
WORKDIR /app WORKDIR /app
# Bun is 10-20x faster for package installation
COPY package.json bun.lockb ./ COPY package.json bun.lockb ./
RUN bun install RUN bun install
COPY . . COPY . .
RUN bun run build RUN bun run build
# Node.js also available via NVM
CMD ["bun", "run", "start"] CMD ["bun", "run", "start"]
``` ```
### TypeScript Project with Multi-Stage Build ### TypeScript Multi-Stage Build
```dockerfile ```dockerfile
# Build stage # Build stage
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node AS builder FROM code.foss.global/host.today/ht-docker-node:alpine-node AS builder
WORKDIR /app WORKDIR /app
COPY package*.json ./ COPY package*.json ./
RUN pnpm install RUN pnpm install
COPY tsconfig.json ./ COPY tsconfig.json ./
COPY src ./src COPY src ./src
RUN pnpm build RUN pnpm build
# Production stage # Production stage — only runtime deps
FROM registry.gitlab.com/hosttoday/ht-docker-node:alpine-node FROM code.foss.global/host.today/ht-docker-node:alpine-node
WORKDIR /app WORKDIR /app
COPY package*.json ./ COPY package*.json ./
RUN pnpm install --prod RUN pnpm install --prod
COPY --from=builder /app/dist ./dist COPY --from=builder /app/dist ./dist
EXPOSE 3000
CMD ["node", "dist/index.js"]
```
### Production-Hardened Setup
```dockerfile
FROM code.foss.global/host.today/ht-docker-node:alpine-node
# Non-root user
RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
WORKDIR /app
COPY package*.json ./
RUN pnpm install --frozen-lockfile && pnpm cache clean
COPY --chown=nodejs:nodejs . .
RUN pnpm build
USER nodejs
EXPOSE 3000 EXPOSE 3000
CMD ["node", "dist/index.js"] CMD ["node", "dist/index.js"]
``` ```
--- ---
## 🔧 NVM Usage Patterns ## 🔧 NVM Cheat Sheet
### 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 ```bash
#!/bin/bash # Install a specific version
# NVM is automatically available in bash scripts nvm install 22.5.0
nvm install 20 # Use a version (current shell)
nvm use 20 nvm use 22
npm ci
npm test
```
### Version Switching # Set default (persists across shells / RUN steps)
nvm alias default 22
# Install and switch to latest LTS
nvm install --lts && nvm use --lts
```bash
# List installed versions # List installed versions
nvm ls nvm ls
# Install and switch to latest LTS # Chain in a single Dockerfile RUN
nvm install --lts RUN nvm install 22 && nvm use 22 && npm ci && npm test
nvm use --lts
# Install specific version
nvm install 18.20.0
# Use installed version
nvm use 18
``` ```
--- ---
## 🏗️ Building Multi-Architecture Images ## 🏗️ Building the Images
This project uses [@git.zone/tsdocker](https://code.foss.global/git.zone/tsdocker) for Docker image management. This project uses [@git.zone/tsdocker](https://code.foss.global/git.zone/tsdocker) for Docker image management.
@@ -266,199 +285,43 @@ This project uses [@git.zone/tsdocker](https://code.foss.global/git.zone/tsdocke
# Install tsdocker # Install tsdocker
pnpm install -g @git.zone/tsdocker@latest pnpm install -g @git.zone/tsdocker@latest
# List all discovered Dockerfiles and their tags # Discover all Dockerfiles and their tags
tsdocker list tsdocker list
# Build all images (multi-arch: amd64 + arm64) # Build all images (multi-arch: amd64 + arm64)
tsdocker build tsdocker build
# Test all images # Run all test scripts
tsdocker test tsdocker test
# Push to a specific registry # Push to a specific registry
tsdocker push code.foss.global tsdocker push code.foss.global
``` ```
### Manual Builds ### Manual Build (single image)
For building individual images manually:
```bash ```bash
# Build for both amd64 and arm64, push to registry
docker buildx build \ docker buildx build \
--platform linux/amd64,linux/arm64 \ --platform linux/amd64,linux/arm64 \
-f Dockerfile_alpine-node \ -f Dockerfile_alpine-node \
-t your-registry/your-image:alpine-node \ -t your-registry/your-image:alpine-node \
--push \ --push .
.
``` ```
--- ### Image Dependency Chain
## 📚 Advanced Examples Some images depend on others being in the registry first:
### Docker Compose Setup ```
Dockerfile (:latest) ──► Dockerfile_lts (:lts)
──► Dockerfile_szci (:szci)
──► Dockerfile_fossglobal_preinstalled_* (:fossglobal_preinstalled_<ver>)
```yaml Dockerfile_alpine-node (:alpine-node)
version: '3.8' ──► Dockerfile_alpine-szci (:alpine-szci)
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 The standalone Alpine images (`:alpine-bun`, `:alpine-deno`) have no registry dependencies.
```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
```
--- ---
@@ -467,55 +330,79 @@ USER node
| Feature | Ubuntu `:latest` | Alpine `:alpine-node` | | Feature | Ubuntu `:latest` | Alpine `:alpine-node` |
|---------|------------------|----------------------| |---------|------------------|----------------------|
| Base Size | ~900 MB | ~200 MB | | Base Size | ~900 MB | ~200 MB |
| Build Tools | ✅ Full | ⚠️ Install separately | | Build Tools | ✅ Full (gcc, g++, make, python3) | ⚠️ Install separately (`apk add build-base`) |
| Compatibility | ✅ Maximum | ✅ Good (musl) | | Chromium | ✅ Pre-installed | ❌ |
| Multi-arch | ❌ amd64 only | ✅ amd64, arm64 | | MongoDB | ✅ 8.0 | ❌ |
| Security | ✅ Good | ✅ Excellent (smaller surface) | | Runtimes | Node + Bun + Deno + pnpm | Node + pnpm |
| Speed | Fast | Faster (smaller) | | Compatibility | ✅ Maximum (glibc) | ✅ Good (musl) |
| Use Case | Complex builds | Production, CI/CD | | Multi-arch | ✅ amd64, arm64 | ✅ amd64, arm64 |
| tini init | ✅ | ✅ |
| Best for | Complex builds, E2E tests, full-stack dev | Production, CI/CD, microservices |
--- ---
## 🔗 Useful Links ## 🐛 Troubleshooting
- **GitHub Repository:** https://github.com/HostToday/ht-docker-node ### NVM command not found
- **Docker Hub:** registry.gitlab.com/hosttoday/ht-docker-node
- **NVM Documentation:** https://github.com/nvm-sh/nvm Shouldn't happen in our images, but if it does:
- **Alpine Linux:** https://alpinelinux.org/
- **Node.js Unofficial Builds:** https://unofficial-builds.nodejs.org/ (musl support) ```bash
export NVM_DIR="/usr/local/nvm"
[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
```
### Alpine native module build failures
Some npm packages require native build tools:
```dockerfile
FROM code.foss.global/host.today/ht-docker-node:alpine-node
RUN apk add --no-cache python3 make g++
RUN pnpm install
```
Or use `:alpine-szci` which ships with build tools pre-installed.
### Version not persisting across RUN steps
Each Dockerfile `RUN` creates a new shell. Use `nvm alias default`:
```dockerfile
RUN nvm install 22 && nvm alias default 22
RUN node -v # ✅ v22.x.x
```
--- ---
## 📋 Changelog ## 🔗 Links
See [changelog.md](changelog.md) for detailed version history. - **Source Code:** [code.foss.global/host.today/ht-docker-node](https://code.foss.global/host.today/ht-docker-node)
- **NVM:** [github.com/nvm-sh/nvm](https://github.com/nvm-sh/nvm)
**Latest Updates (v5.0.148):** - **tini:** [github.com/krallin/tini](https://github.com/krallin/tini)
- ✨ Multi-architecture Alpine images (amd64 + arm64) - **tsdocker:** [code.foss.global/git.zone/tsdocker](https://code.foss.global/git.zone/tsdocker)
- ✨ Native Deno support via Alpine edge - **Alpine Linux:** [alpinelinux.org](https://alpinelinux.org/)
- ✨ Bun runtime integration - **Node.js Unofficial Builds:** [unofficial-builds.nodejs.org](https://unofficial-builds.nodejs.org/) (musl support)
- ✨ 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 ## 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. This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
**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. **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 ### 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. 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 or third parties, 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 or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
### Company Information ### Company Information
Task Venture Capital GmbH Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany 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. For any legal inquiries or 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. 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.