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

8
changelog.md
View File

@@ -1,5 +1,13 @@
# Changelog # Changelog
## 2026-01-20 - 1.4.1 - fix(docs)
update README: expand usage, installation, quick start, features, troubleshooting and migration notes
- Expanded README content: new Quick Start, Installation examples, and detailed Features section (containerized testing, smart Docker builds, multi-registry push, multi-architecture support, zero-config start)
- Added troubleshooting and performance tips including registry login guidance and circular dependency advice
- Updated migration notes from legacy npmdocker to @git.zone/tsdocker (command and config key changes, ESM guidance)
- Documentation-only change — no source code modified
## 2026-01-20 - 1.4.0 - feat(tsdocker) ## 2026-01-20 - 1.4.0 - feat(tsdocker)
add multi-registry and multi-arch Docker build/push/pull manager, registry storage, Dockerfile handling, and new CLI commands add multi-registry and multi-arch Docker build/push/pull manager, registry storage, Dockerfile handling, and new CLI commands

555
readme.md
View File

@@ -1,6 +1,6 @@
# @git.zone/tsdocker # @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 ## Issue Reporting and Security
@@ -8,305 +8,454 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
## What is tsdocker? ## 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 ### 🎯 Key Capabilities
- 🔄 **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 - 🧪 **Containerized Testing** — Run your tests in pristine Docker environments
- 🏗️ **Smart Docker Builds** — Automatically discover, sort, and build Dockerfiles by dependency
✨ **Works Everywhere Docker Does** - 🚀 **Multi-Registry Push** — Ship to Docker Hub, GitLab, GitHub Container Registry, and more
- 🔧 **Multi-Architecture** — Build for `amd64` and `arm64` with Docker Buildx
- Docker Toolbox - ⚡ **Zero Config Start** — Works out of the box, scales with your needs
- 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 ## Installation
```bash ```bash
# Global installation (recommended for CLI usage)
npm install -g @git.zone/tsdocker npm install -g @git.zone/tsdocker
# or for project-local installation
# Or project-local installation
pnpm install --save-dev @git.zone/tsdocker pnpm install --save-dev @git.zone/tsdocker
``` ```
## Quick Start ## 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 ```json
{ {
"@git.zone/tsdocker": { "@git.zone/tsdocker": {
"baseImage": "node:20", "baseImage": "node:20",
"command": "npm test", "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 #### Testing Options (Legacy)
tsdocker
```
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 #### Build & Push Options
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 |
|--------|------|-------------|
| `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 | ## Registry Authentication
| ------------ | --------- | ---------------------------------------------------------------------- |
| `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 ### 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`: # Individual registry format
export DOCKER_REGISTRY_URL="registry.gitlab.com"
```yaml export DOCKER_REGISTRY_USER="username"
demoKey: demoValue export DOCKER_REGISTRY_PASSWORD="password"
API_KEY: your-key-here
``` ```
## CLI Commands ### Login Command
### Standard Test Run
```bash ```bash
tsdocker tsdocker login
``` ```
Runs your configured test command in a fresh Docker container. Authenticates with all configured registries.
### 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 ## 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 ```json
{ {
"@git.zone/tsdocker": { "@git.zone/tsdocker": {
"baseImage": "docker:latest", "baseImage": "docker:latest",
"command": "docker run hello-world", "command": "docker version && docker ps",
"dockerSock": true "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 ```json
{ {
"@git.zone/tsdocker": { "@git.zone/tsdocker": {
"baseImage": "node:20-alpine", "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 ```yaml
- `node:20-alpine` — Lightweight Alpine-based images # .gitlab-ci.yml
- `node:lts` — Long-term support Node.js version build:
stage: build
script:
- npm install -g @git.zone/tsdocker
- tsdocker build
- tsdocker push
### CI Integration # GitHub Actions
- name: Build and Push
tsdocker automatically detects CI environments (via `CI=true` env var) and adjusts behavior: run: |
npm install -g @git.zone/tsdocker
- Copies project files into container in CI (instead of mounting) tsdocker login
- Optimizes for CI execution patterns tsdocker build
tsdocker push
## Why tsdocker? env:
DOCKER_REGISTRY_1: "ghcr.io|${{ github.actor }}|${{ secrets.GITHUB_TOKEN }}"
### 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 ## Requirements
- **Docker**: Docker must be installed and accessible via CLI - **Docker** — Docker Engine or Docker Desktop must be installed
- **Node.js**: Version 18 or higher (ESM support required) - **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 Managing Docker workflows manually is tedious:
2. 🔍 Optionally loads environment variables from `qenv.yml` - Remembering build order for dependent images
3. 🐳 Generates a temporary Dockerfile - Pushing to multiple registries with different credentials
4. 🏗️ Builds a Docker image with your base image - Setting up Buildx for multi-arch builds
5. 📦 Mounts your project directory (unless in CI) - Ensuring consistent test environments
6. ▶️ Runs your test command inside the container
7. 📊 Captures the exit code ### ✨ The Solution
8. 🧹 Cleans up containers and images
9. ✅ Exits with the same code as your tests 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 ## 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 ```bash
docker --version docker --version
``` ```
### Tests fail in container but work locally ### Multi-arch build fails
This often indicates environment-specific issues. Check: Make sure Docker Buildx is available:
- 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 ```bash
sudo usermod -aG docker $USER docker buildx version
# Then log out and back in docker buildx create --use
``` ```
## Examples ### Registry authentication fails
### Basic npm test Check your environment variables are set correctly:
```json ```bash
{ echo $DOCKER_REGISTRY_1
"@git.zone/tsdocker": { tsdocker login
"baseImage": "node:20",
"command": "npm test"
}
}
``` ```
### Running pnpm tests ### Circular dependency detected
```json Review your Dockerfiles' `FROM` statements — you have images depending on each other in a loop.
{
"@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 ## Performance Tips
🚀 **Use specific base images**: `node:20-alpine` is much faster to pull than `node:latest` 🚀 **Use specific tags**: `node:20-alpine` is smaller and faster 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 🚀 **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: 🚀 **Use .dockerignore**: Exclude `node_modules`, `.git`, etc. from build context
- Configuration key changed from `npmdocker` to `@git.zone/tsdocker` in `npmextra.json`
- CLI command is now `tsdocker` instead of `npmdocker` ## Migration from Legacy
- Full ESM support with `.js` extensions in imports
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 ## License and Legal Information

2
ts/00_commitinfo_data.ts
View File

@@ -3,6 +3,6 @@
*/ */
export const commitinfo = { export const commitinfo = {
name: '@git.zone/tsdocker', name: '@git.zone/tsdocker',
version: '1.4.0', version: '1.4.1',
description: 'develop npm modules cross platform with docker' description: 'develop npm modules cross platform with docker'
} }