@git.zone/tsdocker

🐳 The ultimate Docker development toolkit for TypeScript projects — build, test, and ship containerized applications with ease.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit 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/ account to submit Pull Requests directly.

What is tsdocker?

tsdocker is a comprehensive Docker development and building tool that handles everything from testing npm packages in clean environments to building and pushing multi-architecture Docker images across multiple registries.

🎯 Key Capabilities

• 🧪 Containerized Testing — Run your tests in pristine Docker environments
• 🏗️ Smart Docker Builds — Automatically discover, sort, and build Dockerfiles by dependency
• 🚀 Multi-Registry Push — Ship to Docker Hub, GitLab, GitHub Container Registry, and more
• 🔧 Multi-Architecture — Build for amd64 and arm64 with Docker Buildx
• ⚡ Zero Config Start — Works out of the box, scales with your needs

Installation

# Global installation (recommended for CLI usage)
npm install -g @git.zone/tsdocker

# Or project-local installation
pnpm install --save-dev @git.zone/tsdocker

Quick Start

🧪 Run Tests in Docker

The simplest use case — run your tests in a clean container:

tsdocker

This pulls your configured base image, mounts your project, and executes your test command in isolation.

🏗️ Build Docker Images

Got Dockerfile files? Build them all with automatic dependency ordering:

tsdocker build

tsdocker will:

1. 🔍 Discover all Dockerfile* files in your project
2. 📊 Analyze FROM dependencies between them
3. 🔄 Sort them topologically
4. 🏗️ Build each image in the correct order

📤 Push to Registries

Ship your images to one or all configured registries:

# Push to all configured registries
tsdocker push

# Push to a specific registry
tsdocker push registry.gitlab.com

CLI Commands

Command	Description
tsdocker	Run tests in a fresh Docker container
tsdocker build	Build all Dockerfiles with dependency ordering
tsdocker push [registry]	Push images to configured registries
tsdocker pull <registry>	Pull images from a specific registry
tsdocker test	Run container test scripts (test_*.sh)
tsdocker login	Authenticate with configured registries
tsdocker list	Display discovered Dockerfiles and their dependencies
tsdocker clean --all	⚠️ Aggressively clean Docker environment
tsdocker vscode	Launch containerized VS Code in browser

Configuration

Configure tsdocker in your package.json or npmextra.json:

{
  "@git.zone/tsdocker": {
    "baseImage": "node:20",
    "command": "npm test",
    "dockerSock": false,
    "registries": ["registry.gitlab.com", "docker.io"],
    "registryRepoMap": {
      "registry.gitlab.com": "myorg/myproject"
    },
    "buildArgEnvMap": {
      "NODE_VERSION": "NODE_VERSION"
    },
    "platforms": ["linux/amd64", "linux/arm64"],
    "push": false,
    "testDir": "./test"
  }
}

Configuration Options

Testing Options (Legacy)

Option	Type	Description
baseImage	string	Docker image for test environment (default: hosttoday/ht-docker-node:npmdocker)
command	string	Command to run inside container (default: npmci npm test)
dockerSock	boolean	Mount Docker socket for DinD scenarios (default: false)

Build & Push Options

Option	Type	Description
registries	string[]	Registry URLs to push to
registryRepoMap	object	Map registries to different repository paths
buildArgEnvMap	object	Map Docker build ARGs to environment variables
platforms	string[]	Target architectures (default: ["linux/amd64"])
push	boolean	Auto-push after build (default: false)
testDir	string	Directory containing test scripts

Registry Authentication

Environment Variables

# Pipe-delimited format (supports DOCKER_REGISTRY_1 through DOCKER_REGISTRY_10)
export DOCKER_REGISTRY_1="registry.gitlab.com|username|password"
export DOCKER_REGISTRY_2="docker.io|username|password"

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

Login Command

tsdocker login

Authenticates with all configured registries.

Advanced Usage

🔀 Multi-Architecture Builds

Build for multiple platforms using Docker Buildx:

{
  "@git.zone/tsdocker": {
    "platforms": ["linux/amd64", "linux/arm64"]
  }
}

tsdocker automatically sets up a Buildx builder when multiple platforms are specified.

📦 Dockerfile Naming Conventions

tsdocker discovers files matching Dockerfile*:

File Name	Version Tag
Dockerfile	latest
Dockerfile_v1.0.0	v1.0.0
Dockerfile_alpine	alpine
Dockerfile_##version##	Uses package.json version

🔗 Dependency-Aware Builds

If you have multiple Dockerfiles that depend on each other:

# Dockerfile_base
FROM node:20-alpine
RUN npm install -g typescript

# Dockerfile_app
FROM myproject:base
COPY . .
RUN npm run build

tsdocker automatically detects that Dockerfile_app depends on Dockerfile_base and builds them in the correct order.

🧪 Container Test Scripts

Create test scripts in your test directory:

# test/test_latest.sh
#!/bin/bash
node --version
npm --version
echo "Container tests passed!"

Run with:

tsdocker test

🔧 Build Args from Environment

Pass environment variables as Docker build arguments:

{
  "@git.zone/tsdocker": {
    "buildArgEnvMap": {
      "NPM_TOKEN": "NPM_TOKEN",
      "NODE_VERSION": "NODE_VERSION"
    }
  }
}

ARG NPM_TOKEN
ARG NODE_VERSION=20
FROM node:${NODE_VERSION}
RUN echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc

🐳 Docker-in-Docker Testing

Test Docker-related tools by mounting the Docker socket:

{
  "@git.zone/tsdocker": {
    "baseImage": "docker:latest",
    "command": "docker version && docker ps",
    "dockerSock": true
  }
}

📋 Listing Dockerfiles

Inspect your project's Dockerfiles and their relationships:

tsdocker list

Output:

Discovered Dockerfiles:
========================

1. Dockerfile_base
   Tag: myproject:base
   Base Image: node:20-alpine
   Version: base

2. Dockerfile_app
   Tag: myproject:app
   Base Image: myproject:base
   Version: app
   Depends on: myproject:base

🗺️ Registry Repo Mapping

Use different repository names for different registries:

{
  "@git.zone/tsdocker": {
    "registries": ["registry.gitlab.com", "docker.io"],
    "registryRepoMap": {
      "registry.gitlab.com": "mygroup/myproject",
      "docker.io": "myuser/myproject"
    }
  }
}

Environment Variables

qenv Integration

tsdocker automatically loads environment variables from qenv.yml:

# qenv.yml
API_KEY: your-api-key
DATABASE_URL: postgres://localhost/test

These are injected into your test container automatically.

Examples

Basic Test Configuration

{
  "@git.zone/tsdocker": {
    "baseImage": "node:20",
    "command": "npm test"
  }
}

Full Production Setup

{
  "@git.zone/tsdocker": {
    "baseImage": "node:20-alpine",
    "command": "pnpm test",
    "registries": ["registry.gitlab.com", "ghcr.io", "docker.io"],
    "registryRepoMap": {
      "registry.gitlab.com": "myorg/myapp",
      "ghcr.io": "myorg/myapp",
      "docker.io": "myuser/myapp"
    },
    "buildArgEnvMap": {
      "NPM_TOKEN": "NPM_TOKEN"
    },
    "platforms": ["linux/amd64", "linux/arm64"],
    "testDir": "./docker-tests"
  }
}

CI/CD Integration

# .gitlab-ci.yml
build:
  stage: build
  script:
    - npm install -g @git.zone/tsdocker
    - tsdocker build
    - tsdocker push

# GitHub Actions
- name: Build and Push
  run: |
    npm install -g @git.zone/tsdocker
    tsdocker login
    tsdocker build
    tsdocker push
  env:
    DOCKER_REGISTRY_1: "ghcr.io|${{ github.actor }}|${{ secrets.GITHUB_TOKEN }}"

Requirements

• Docker — Docker Engine or Docker Desktop must be installed
• Node.js — Version 18 or higher (ESM support required)
• Docker Buildx — Required for multi-architecture builds (included in Docker Desktop)

Why tsdocker?

🎯 The Problem

Managing Docker workflows manually is tedious:

• Remembering build order for dependent images
• Pushing to multiple registries with different credentials
• Setting up Buildx for multi-arch builds
• Ensuring consistent test environments

✨ The Solution

tsdocker automates the entire workflow:

• One command to build all images in dependency order
• One command to push to all registries
• Automatic Buildx setup for multi-platform builds
• Consistent containerized test environments

TypeScript API

tsdocker exposes its types for programmatic use:

import type { ITsDockerConfig } from '@git.zone/tsdocker/dist_ts/interfaces/index.js';
import { TsDockerManager } from '@git.zone/tsdocker/dist_ts/classes.tsdockermanager.js';

const config: ITsDockerConfig = {
  baseImage: 'node:20',
  command: 'npm test',
  dockerSock: false,
  keyValueObject: {},
  registries: ['docker.io'],
  platforms: ['linux/amd64'],
};

const manager = new TsDockerManager(config);
await manager.prepare();
await manager.build();
await manager.push();

Troubleshooting

"docker not found"

Ensure Docker is installed and in your PATH:

docker --version

Multi-arch build fails

Make sure Docker Buildx is available:

docker buildx version
docker buildx create --use

Registry authentication fails

Check your environment variables are set correctly:

echo $DOCKER_REGISTRY_1
tsdocker login

Circular dependency detected

Review your Dockerfiles' FROM statements — you have images depending on each other in a loop.

Performance Tips

🚀 Use specific tags: node:20-alpine is smaller and faster than node:latest

🚀 Leverage caching: Docker layers are cached — your builds get faster over time

🚀 Prune regularly: docker system prune reclaims disk space

🚀 Use .dockerignore: Exclude node_modules, .git, etc. from build context

Migration from Legacy

Previously published as npmdocker, now @git.zone/tsdocker:

Old	New
npmdocker command	tsdocker command
"npmdocker" config key	"@git.zone/tsdocker" config key
CommonJS	ESM with .js imports

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the 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.

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 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

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

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.