git.zone/tsdocker
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(docs): update README: expand usage, installation, quick start, features, troubleshooting and migration notes

Browse Source
This commit is contained in:
Jürgen Kunz
2026-01-20 12:28:28 +00:00
parent 6922d19454
commit 808066d8c3
3 changed files with 361 additions and 204 deletions
Download Patch File Download Diff File Expand all files Collapse all files

555
readme.md
View File

@@ -1,6 +1,6 @@
# @git.zone/tsdocker
> 🐳 Cross-platform npm module development with Docker — test your packages in clean, reproducible Linux environments every time.
> 🐳 The ultimate Docker development toolkit for TypeScript projects — build, test, and ship containerized applications with ease.
## Issue Reporting and Security
@@ -8,305 +8,454 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
## What is tsdocker?
**tsdocker** provides containerized testing environments for npm packages, ensuring your code works consistently across different systems. It's perfect for:
**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.
- 🧪 **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
### 🎯 Key Capabilities
## 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
- 🧪 **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 for project-local installation
# Or project-local installation
pnpm install --save-dev @git.zone/tsdocker
```
## Quick Start
### 1. Configure Your Project
### 🧪 Run Tests in Docker
Create an `npmextra.json` file in your project root:
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
"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"
}
}
```
### 2. Run Your Tests
### Configuration Options
```bash
tsdocker
```
#### Testing Options (Legacy)
That's it! tsdocker will:
| 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`) |
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
#### Build & Push Options
## Configuration 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 |
| 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 |
## Registry Authentication
### Environment Variables
If you have a `qenv.yml` file in your project, tsdocker automatically loads and injects those environment variables into your test container.
```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"
Example `qenv.yml`:
```yaml
demoKey: demoValue
API_KEY: your-key-here
# Individual registry format
export DOCKER_REGISTRY_URL="registry.gitlab.com"
export DOCKER_REGISTRY_USER="username"
export DOCKER_REGISTRY_PASSWORD="password"
```
## CLI Commands
### Standard Test Run
### Login Command
```bash
tsdocker
tsdocker login
```
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`.
Authenticates with all configured registries.
## Advanced Usage
### Docker-in-Docker Testing
### 🔀 Multi-Architecture Builds
If you need to run Docker commands inside your test container (e.g., testing Docker-related tools):
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 run hello-world",
"command": "docker version && docker ps",
"dockerSock": true
}
}
```
Setting `"dockerSock": true` mounts the host's Docker socket into the container.
### 📋 Listing Dockerfiles
### Custom Base Images
Inspect your project's Dockerfiles and their relationships:
You can use any Docker image as your base:
```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": "npm test"
"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"
}
}
```
Popular choices:
### CI/CD Integration
- `node:20` — Official Node.js images
- `node:20-alpine` — Lightweight Alpine-based images
- `node:lts` — Long-term support Node.js version
```yaml
# .gitlab-ci.yml
build:
stage: build
script:
- npm install -g @git.zone/tsdocker
- tsdocker build
- tsdocker push
### 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',
},
};
# 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 must be installed and accessible via CLI
- **Node.js**: Version 18 or higher (ESM support required)
- **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)
## How It Works
## Why tsdocker?
Under the hood, tsdocker:
### 🎯 The Problem
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
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 on this machine"
### "docker not found"
Make sure Docker is installed and the `docker` command is in your PATH:
Ensure Docker is installed and in your PATH:
```bash
docker --version
```
### Tests fail in container but work locally
### Multi-arch build fails
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`:
Make sure Docker Buildx is available:
```bash
sudo usermod -aG docker $USER
# Then log out and back in
docker buildx version
docker buildx create --use
```
## Examples
### Registry authentication fails
### Basic npm test
Check your environment variables are set correctly:
```json
{
"@git.zone/tsdocker": {
"baseImage": "node:20",
"command": "npm test"
}
}
```bash
echo $DOCKER_REGISTRY_1
tsdocker login
```
### Running pnpm tests
### Circular dependency detected
```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
}
}
```
Review your Dockerfiles' `FROM` statements — you have images depending on each other in a loop.
## 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
🚀 **Use specific tags**: `node:20-alpine` is smaller and faster than `node:latest`
## Migration from legacy npmdocker
🚀 **Leverage caching**: Docker layers are cached — your builds get faster over time
This package was previously published under the `npmdocker` name. It is now available as `@git.zone/tsdocker` with modernized ESM support and updated dependencies.
🚀 **Prune regularly**: `docker system prune` reclaims disk space
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
🚀 **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