tsdocker/readme.md

# @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/](https://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/](https://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

```bash
# 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:

```bash
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:

```bash
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:

```bash
# 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`:

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

```bash
# 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

```bash
tsdocker login
```

Authenticates with all configured registries.

## Advanced Usage

### 🔀 Multi-Architecture Builds

Build for multiple platforms using Docker Buildx:

```json
{
  "@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
# 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:

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

Run with:

```bash
tsdocker test
```

### 🔧 Build Args from Environment

Pass environment variables as Docker build arguments:

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

```dockerfile
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:

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

### 📋 Listing Dockerfiles

Inspect your project's Dockerfiles and their relationships:

```bash
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:

```json
{
  "@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`:

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

These are injected into your test container automatically.

## Examples

### Basic Test Configuration

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

### Full Production Setup

```json
{
  "@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

```yaml
# .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:

```typescript
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:

```bash
docker --version
```

### Multi-arch build fails

Make sure Docker Buildx is available:

```bash
docker buildx version
docker buildx create --use
```

### Registry authentication fails

Check your environment variables are set correctly:

```bash
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](./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.