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:
```bash
docker buildx build --platform linux/amd64,linux/arm64 -f Dockerfile_xxx --push .
```

## CI/CD Integration

The images work with npmci for automated building:
```bash
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