tsdocker/readme.hints.md

tsdocker Project Hints

Module Purpose

tsdocker is a comprehensive Docker development and building tool. It provides:

• Testing npm modules in clean Docker environments (legacy feature)
• Building Dockerfiles with dependency ordering
• Multi-registry push/pull support
• Multi-architecture builds (amd64/arm64)

New CLI Commands (2026-01-19)

Command	Description
tsdocker	Run tests in container (legacy default behavior)
tsdocker build	Build all Dockerfiles with dependency ordering
tsdocker push [registry]	Push images to configured registries
tsdocker pull <registry>	Pull images from registry
tsdocker test	Run container tests (test scripts)
tsdocker login	Login to configured registries
tsdocker list	List discovered Dockerfiles and dependencies
tsdocker clean --all	Clean up Docker environment
tsdocker vscode	Start VS Code in Docker

Configuration

Configure in package.json under @git.zone/tsdocker:

{
  "@git.zone/tsdocker": {
    "registries": ["registry.gitlab.com", "docker.io"],
    "registryRepoMap": {
      "registry.gitlab.com": "host.today/ht-docker-node"
    },
    "buildArgEnvMap": {
      "NODE_VERSION": "NODE_VERSION"
    },
    "platforms": ["linux/amd64", "linux/arm64"],
    "push": false,
    "testDir": "./test"
  }
}

Configuration Options

• baseImage: Base Docker image for testing (legacy)
• command: Command to run in container (legacy)
• dockerSock: Mount Docker socket (legacy)
• registries: Array of registry URLs to push to
• registryRepoMap: Map registry URLs to different repo paths
• buildArgEnvMap: Map Docker build ARGs to environment variables
• platforms: Target architectures for buildx
• push: Auto-push after build
• testDir: Directory containing test scripts

Registry Authentication

Set environment variables for registry login:

# Pipe-delimited format (numbered 1-10)
export DOCKER_REGISTRY_1="registry.gitlab.com|username|password"
export DOCKER_REGISTRY_2="docker.io|username|password"

# Or individual registry format
export DOCKER_REGISTRY_URL="registry.gitlab.com"
export DOCKER_REGISTRY_USER="username"
export DOCKER_REGISTRY_PASSWORD="password"

File Structure

ts/
├── index.ts                      (entry point)
├── tsdocker.cli.ts               (CLI commands)
├── tsdocker.config.ts            (configuration)
├── tsdocker.plugins.ts           (plugin imports)
├── tsdocker.docker.ts            (legacy test runner)
├── tsdocker.snippets.ts          (Dockerfile generation)
├── classes.dockerfile.ts         (Dockerfile management)
├── classes.dockerregistry.ts     (registry authentication)
├── classes.registrystorage.ts    (registry storage)
├── classes.tsdockermanager.ts    (orchestrator)
└── interfaces/
    └── index.ts                  (type definitions)

Dependencies

• @push.rocks/lik: Object mapping utilities
• @push.rocks/smartfs: Filesystem operations
• @push.rocks/smartshell: Shell command execution
• @push.rocks/smartcli: CLI framework
• @push.rocks/projectinfo: Project metadata

Parallel Builds

--parallel flag enables level-based parallel Docker builds:

tsdocker build --parallel           # parallel, default concurrency (4)
tsdocker build --parallel=8         # parallel, concurrency 8
tsdocker build --parallel --cached  # works with both modes

Implementation: Dockerfile.computeLevels() groups topologically sorted Dockerfiles into dependency levels. Dockerfile.runWithConcurrency() provides a worker-pool pattern for bounded concurrency. Both are public static methods on the Dockerfile class. The parallel logic exists in both Dockerfile.buildDockerfiles() (standard mode) and TsDockerManager.build() (cached mode).

OCI Distribution API Push (v1.16+)

All builds now go through a persistent local registry (localhost:5234) with volume storage at .nogit/docker-registry/. Pushes use the RegistryCopy class (ts/classes.registrycopy.ts) which implements the OCI Distribution API to copy images (including multi-arch manifest lists) from the local registry to remote registries. This replaces the old docker tag + docker push approach that only worked for single-platform images.

Key classes:

• RegistryCopy — HTTP-based OCI image copy (auth, blob transfer, manifest handling)
• Dockerfile.push() — Now delegates to RegistryCopy.copyImage()
• Dockerfile.needsLocalRegistry() — Always returns true
• Dockerfile.startLocalRegistry() — Uses persistent volume mount

The config.push field is now a no-op (kept for backward compat).

Build Status

• Build: ✅ Passes
• Legacy test functionality preserved
• New Docker build functionality added

Previous Upgrades (2025-11-22)

• Updated all @git.zone/_ dependencies to @git.zone/_ scope
• Updated all @pushrocks/_ dependencies to @push.rocks/_ scope
• Migrated from smartfile v8 to smartfs v1.1.0