ht-docker-tools/readme.hints.md

Technical Notes - ht-docker-tools

Architecture Overview

This repository provides Docker images in two variants:

1. Official Base Images: Extend official images with Deno runtime
2. Alpine Images: Standalone Alpine-based with full NVM + Node.js + Deno stack

NVM Implementation (Alpine Images)

NVM is a bash function, not a binary. This creates challenges in Docker contexts:

Three Context Solutions

1. Build-time (Dockerfile RUN commands)

   • Uses bash-with-nvm wrapper script as SHELL directive
   • Loads NVM before executing each RUN command

2. Runtime (CI/CD bash -c commands)

   • docker-entrypoint.sh handles bash -c commands
   • Injects bashrc sourcing automatically
   • ENV BASH_ENV=/etc/bash.bashrc enables non-interactive shell support

3. Interactive shells

   • /etc/bash.bashrc configured with NVM initialization
   • Works in interactive terminal sessions

Key Files

• image_support_files/bash-with-nvm - Build-time NVM wrapper
• image_support_files/docker-entrypoint.sh - Runtime NVM support
• /etc/bash.bashrc - Created during build with NVM init

Official Base Image Considerations

ClickHouse (Debian-based)

• Base: clickhouse/clickhouse-server
• Deno installed via curl installer
• Preserves original entrypoint

MongoDB (Debian-based)

• Base: mongo:latest
• Deno installed via curl installer
• Preserves original entrypoint

MinIO (RHEL-based minimal)

• Base: minio/minio:latest
• Uses microdnf for package management
• Requires USER switch (root for install, minio for runtime)

Caddy (Alpine-based)

• Base: caddy:latest
• Deno installed from Alpine edge repository
• Already Alpine, so minimal modification needed

Redis (Debian-based)

• Base: redis:latest
• Deno installed via curl installer
• Preserves original entrypoint

Alpine Package Availability

Tool	Package	Repository
MongoDB	mongodb, mongodb-tools	edge/community
MinIO	minio	edge/community
ClickHouse	clickhouse	edge/community
Caddy	caddy	edge/community
Redis	redis	main
Deno	deno	edge/community

All Alpine images use alpine:edge to access community packages.

Version Information

• NVM: v0.40.1
• Node.js LTS: 20.18.2
• Uses unofficial-builds.nodejs.org for musl (Alpine) compatibility

Multi-Architecture

Alpine images support:

• linux/amd64 (x86_64)
• linux/arm64 (aarch64/Apple Silicon)

Build with buildx:

docker buildx build --platform linux/amd64,linux/arm64 -f Dockerfile_xxx --push .

CI/CD Integration

The images work with npmci for automated building:

npmci docker login
npmci docker build
npmci docker test
npmci docker push code.foss.global

Testing

Run the test script to verify:

• Deno availability in all images
• NVM availability in Alpine images
• Node.js version in Alpine images
• NVM version switching capability