tsdocker/readme.md

# @git.zone/tsdocker

> 🐳 Cross-platform npm module development with Docker — test your packages in clean, reproducible Linux environments every time.

## 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** provides containerized testing environments for npm packages, ensuring your code works consistently across different systems. It's perfect for:

- 🧪 **Testing in clean environments** — Every test run starts fresh, just like CI
- 🔄 **Reproducing CI behavior locally** — No more "works on my machine" surprises
- 🐧 **Cross-platform development** — Develop on macOS/Windows, test on Linux
- 🚀 **Quick validation** — Spin up isolated containers for testing without polluting your system

## Features

✨ **Works Everywhere Docker Does**

- Docker Toolbox
- Native Docker Desktop
- Docker-in-Docker (DinD)
- Mounted docker.sock scenarios

🔧 **Flexible Configuration**

- Custom base images
- Configurable test commands
- Environment variable injection via qenv
- Optional docker.sock mounting for nested container tests

📦 **TypeScript-First**

- Full TypeScript support with excellent IntelliSense
- Type-safe configuration
- Modern ESM with async/await patterns throughout

## Installation

```bash
npm install -g @git.zone/tsdocker
# or for project-local installation
pnpm install --save-dev @git.zone/tsdocker
```

## Quick Start

### 1. Configure Your Project

Create an `npmextra.json` file in your project root:

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

### 2. Run Your Tests

```bash
tsdocker
```

That's it! tsdocker will:

1. ✅ Verify Docker is available
2. 🏗️ Build a test container with your specified base image
3. 📂 Mount your project directory
4. 🚀 Execute your test command
5. 🧹 Clean up automatically

## Configuration Options

| Option       | Type      | Description                                                            |
| ------------ | --------- | ---------------------------------------------------------------------- |
| `baseImage`  | `string`  | Docker image to use as the test environment base                       |
| `command`    | `string`  | CLI command to execute inside the container                            |
| `dockerSock` | `boolean` | Whether to mount `/var/run/docker.sock` for Docker-in-Docker scenarios |

### Environment Variables

If you have a `qenv.yml` file in your project, tsdocker automatically loads and injects those environment variables into your test container.

Example `qenv.yml`:

```yaml
demoKey: demoValue
API_KEY: your-key-here
```

## CLI Commands

### Standard Test Run

```bash
tsdocker
```

Runs your configured test command in a fresh Docker container.

### Clean Docker Environment

```bash
tsdocker clean --all
```

⚠️ **WARNING**: This aggressively cleans your Docker environment by:

- Killing all running containers
- Removing all stopped containers
- Removing dangling images
- Removing all images
- Removing dangling volumes

Use with caution!

### VSCode in Docker

```bash
tsdocker vscode
```

Launches a containerized VS Code instance accessible via browser at `testing-vscode.git.zone:8443`.

## Advanced Usage

### Docker-in-Docker Testing

If you need to run Docker commands inside your test container (e.g., testing Docker-related tools):

```json
{
  "@git.zone/tsdocker": {
    "baseImage": "docker:latest",
    "command": "docker run hello-world",
    "dockerSock": true
  }
}
```

Setting `"dockerSock": true` mounts the host's Docker socket into the container.

### Custom Base Images

You can use any Docker image as your base:

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

Popular choices:

- `node:20` — Official Node.js images
- `node:20-alpine` — Lightweight Alpine-based images
- `node:lts` — Long-term support Node.js version

### CI Integration

tsdocker automatically detects CI environments (via `CI=true` env var) and adjusts behavior:

- Copies project files into container in CI (instead of mounting)
- Optimizes for CI execution patterns

## Why tsdocker?

### The Problem

Local development environments drift over time. You might have:

- Stale global packages
- Modified system configurations
- Cached dependencies
- Different Node.js versions

Your tests pass locally but fail in CI — or vice versa.

### The Solution

tsdocker ensures every test run happens in a **clean, reproducible environment**, just like your CI pipeline. This means:

✅ Consistent behavior between local and CI
✅ No dependency pollution between test runs
✅ Easy cross-platform testing
✅ Reproducible bug investigations

## TypeScript Usage

tsdocker is built with TypeScript and provides full type definitions:

```typescript
import type { IConfig } from '@git.zone/tsdocker/dist_ts/tsdocker.config.js';

const config: IConfig = {
  baseImage: 'node:20',
  command: 'npm test',
  dockerSock: false,
  keyValueObject: {
    NODE_ENV: 'test',
  },
};
```

## Requirements

- **Docker**: Docker must be installed and accessible via CLI
- **Node.js**: Version 18 or higher (ESM support required)

## How It Works

Under the hood, tsdocker:

1. 📋 Reads your `npmextra.json` configuration
2. 🔍 Optionally loads environment variables from `qenv.yml`
3. 🐳 Generates a temporary Dockerfile
4. 🏗️ Builds a Docker image with your base image
5. 📦 Mounts your project directory (unless in CI)
6. ▶️ Runs your test command inside the container
7. 📊 Captures the exit code
8. 🧹 Cleans up containers and images
9. ✅ Exits with the same code as your tests

## Troubleshooting

### "docker not found on this machine"

Make sure Docker is installed and the `docker` command is in your PATH:

```bash
docker --version
```

### Tests fail in container but work locally

This often indicates environment-specific issues. Check:

- Are all dependencies in `package.json`? (not relying on global packages)
- Does your code have hardcoded paths?
- Are environment variables set correctly?

### Permission errors with docker.sock

If using `dockerSock: true`, ensure your user has permissions to access `/var/run/docker.sock`:

```bash
sudo usermod -aG docker $USER
# Then log out and back in
```

## Examples

### Basic npm test

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

### Running pnpm tests

```json
{
  "@git.zone/tsdocker": {
    "baseImage": "node:20",
    "command": "corepack enable && pnpm install && pnpm test"
  }
}
```

### Testing Docker-based tools

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

## Performance Tips

🚀 **Use specific base images**: `node:20-alpine` is much faster to pull than `node:latest`
🚀 **Layer caching**: Docker caches image layers — your base image only downloads once
🚀 **Prune regularly**: Run `docker system prune` periodically to reclaim disk space

## Migration from legacy npmdocker

This package was previously published under the `npmdocker` name. It is now available as `@git.zone/tsdocker` with modernized ESM support and updated dependencies.

Key changes:
- Configuration key changed from `npmdocker` to `@git.zone/tsdocker` in `npmextra.json`
- CLI command is now `tsdocker` instead of `npmdocker`
- Full ESM support with `.js` extensions in 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.