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

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