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

BREAKING CHANGE(cli): remove legacy container test runner and make the default command show the man page

Browse Source
This commit is contained in:
Jürgen Kunz
2026-03-12 10:50:34 +00:00
parent 8f0514d10e
commit 0f445b4c86
14 changed files with 239 additions and 445 deletions
Download Patch File Download Diff File Expand all files Collapse all files

241
readme.md
View File

@@ -12,13 +12,15 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
### 🎯 Key Capabilities
- 🧪 **Containerized Testing** — Run your tests in pristine Docker environments
- 🏗️ **Smart Docker Builds** — Automatically discover, sort, and build Dockerfiles by dependency
- 🌍 **True Multi-Architecture** — Build for `amd64` and `arm64` simultaneously with Docker Buildx
- 🚀 **Multi-Registry Push** — Ship to Docker Hub, GitLab, GitHub Container Registry, and more via OCI Distribution API
- ⚡ **Parallel Builds** — Level-based parallel builds with configurable concurrency
- 🗄️ **Persistent Local Registry** — All images flow through a local OCI registry with persistent storage
- 📦 **Build Caching** — Skip unchanged Dockerfiles with content-hash caching
- 🎯 **Dockerfile Filtering** — Build or push only specific Dockerfiles using glob patterns
- 🔁 **Resilient Push** — Automatic retry with exponential backoff, timeouts, and token refresh for rock-solid pushes
- 🏭 **CI-Safe Isolation** — Unique sessions per invocation prevent collisions in parallel CI pipelines
- 🔧 **Zero Config Start** — Works out of the box, scales with your needs
## Installation
@@ -33,16 +35,6 @@ 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:
@@ -68,15 +60,33 @@ tsdocker push
# Push to a specific registry
tsdocker push --registry=registry.gitlab.com
# Push without rebuilding (use existing images in local registry)
tsdocker push --no-build
```
Under the hood, `tsdocker push` uses the **OCI Distribution API** to copy images directly from the local registry to remote registries. This means multi-arch manifest lists are preserved end-to-end — no more single-platform-only pushes.
Under the hood, `tsdocker push` uses the **OCI Distribution API** to copy images directly from the local registry to remote registries. This means multi-arch manifest lists are preserved end-to-end — no more single-platform-only pushes. Every request is protected with **automatic retry** (up to 6 attempts with exponential backoff) and **5-minute timeouts**, so transient network issues don't kill your push mid-transfer.
### 🎯 Build Only Specific Dockerfiles
Target specific Dockerfiles by name pattern — dependencies are resolved automatically:
```bash
# Build only the base image
tsdocker build Dockerfile_base
# Build anything matching a glob pattern
tsdocker build Dockerfile_app*
# Push specific images only (skip build phase)
tsdocker push --no-build Dockerfile_api Dockerfile_web
```
## CLI Commands
| Command | Description |
|---------|-------------|
| `tsdocker` | Run tests in a fresh Docker container (legacy mode) |
| `tsdocker` | Show usage / man page |
| `tsdocker build` | Build all Dockerfiles with dependency ordering |
| `tsdocker push` | Build + push images to configured registries |
| `tsdocker pull <registry>` | Pull images from a specific registry |
@@ -84,12 +94,12 @@ Under the hood, `tsdocker push` uses the **OCI Distribution API** to copy images
| `tsdocker login` | Authenticate with configured registries |
| `tsdocker list` | Display discovered Dockerfiles and their dependencies |
| `tsdocker clean` | Interactively clean Docker environment |
| `tsdocker vscode` | Launch containerized VS Code in browser |
### Build Flags
| Flag | Description |
|------|-------------|
| `<patterns>` | Positional Dockerfile name patterns (e.g. `Dockerfile_base`, `Dockerfile_app*`) |
| `--platform=linux/arm64` | Override build platform for a single architecture |
| `--timeout=600` | Build timeout in seconds |
| `--no-cache` | Force rebuild without Docker layer cache |
@@ -99,6 +109,14 @@ Under the hood, `tsdocker push` uses the **OCI Distribution API** to copy images
| `--parallel=8` | Parallel builds with custom concurrency |
| `--context=mycontext` | Use a specific Docker context |
### Push Flags
| Flag | Description |
|------|-------------|
| `<patterns>` | Positional Dockerfile name patterns to select which images to push |
| `--registry=<url>` | Push to a single specific registry instead of all configured |
| `--no-build` | Skip the build phase; only push existing images from local registry |
### Clean Flags
| Flag | Description |
@@ -138,16 +156,6 @@ Configure tsdocker in your `package.json` or `npmextra.json` under the `@git.zon
| `platforms` | `string[]` | `["linux/amd64"]` | Target architectures for multi-arch builds |
| `testDir` | `string` | `./test` | Directory containing test scripts |
#### Legacy Testing Options
These options configure the `tsdocker` default command (containerized test runner):
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `baseImage` | `string` | `hosttoday/ht-docker-node:npmdocker` | Docker image for test environment |
| `command` | `string` | `npmci npm test` | Command to run inside the container |
| `dockerSock` | `boolean` | `false` | Mount Docker socket for DinD scenarios |
## Architecture: How tsdocker Works
tsdocker uses a **local OCI registry** as the canonical store for all built images. This design solves fundamental problems with Docker's local daemon, which cannot hold multi-architecture manifest lists.
@@ -155,36 +163,37 @@ tsdocker uses a **local OCI registry** as the canonical store for all built imag
### 📐 Build Flow
```
┌─────────────────────────────────────────────────┐
│ tsdocker build │
│ │
│ 1. Start local registry (localhost:5234) │
│ └── Persistent volume: .nogit/docker-registry/
│ │
│ 2. For each Dockerfile (topological order): │
│ ├── Multi-platform: buildx --push → registry │
│ └── Single-platform: docker build → registry │
│ │
│ 3. Stop local registry (data persists on disk) │
└─────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────┐
│ tsdocker build │
│ │
│ 1. Start local registry (localhost:<dynamic-port>) │
│ └── Persistent volume: .nogit/docker-registry/ │
│ │
│ 2. For each Dockerfile (topological order): │
│ ├── Multi-platform: buildx --push → registry │
│ └── Single-platform: docker build → registry │
│ │
│ 3. Stop local registry (data persists on disk) │
└─────────────────────────────────────────────────────┘
```
### 📤 Push Flow
```
┌──────────────────────────────────────────────────┐
│ tsdocker push │
│ │
│ 1. Start local registry (loads persisted data) │
│ │
│ 2. For each image × each remote registry: │
│ └── OCI Distribution API copy: │
│ ├── Fetch manifest (single or multi-arch) │
│ ├── Copy blobs (skip if already exist) │
│ └── Push manifest with destination tag │
│ │
│ 3. Stop local registry │
└──────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────┐
│ tsdocker push │
│ │
│ 1. Start local registry (loads persisted data) │
│ │
│ 2. For each image × each remote registry: │
│ └── OCI Distribution API copy (with retry): │
│ ├── Fetch manifest (single or multi-arch) │
│ ├── Copy blobs (skip if already exist) │
│ ├── Retry up to 6× with exponential backoff │
│ └── Push manifest with destination tag │
│ │
│ 3. Stop local registry │
└────────────────────────────────────────────────────────┘
```
### 🔑 Why a Local Registry?
@@ -196,6 +205,49 @@ tsdocker uses a **local OCI registry** as the canonical store for all built imag
| Images lost between build and push phases | Persistent storage at `.nogit/docker-registry/` survives restarts |
| Redundant blob uploads on incremental pushes | HEAD checks skip blobs that already exist on the remote |
### 🔁 Resilient Push
The OCI Distribution API client wraps every HTTP request with:
- **Timeouts** — 5-minute timeout for blob operations, 30-second timeout for auth/metadata calls via `AbortSignal.timeout()`
- **Automatic Retry** — Up to 6 attempts with exponential backoff (1s → 2s → 4s → 8s → 16s → 32s)
- **Smart Retry Logic** — Retries on network errors (`ECONNRESET`, `fetch failed`) and 5xx server errors; does NOT retry 4xx client errors
- **Token Refresh** — On 401 responses, the cached auth token is cleared so the next retry re-authenticates automatically
This means transient issues like stale connection pools, brief network blips, or token expiry during long multi-arch pushes (56+ blob operations) are handled gracefully instead of killing the entire transfer.
### 🏭 CI-Safe Session Isolation
Every tsdocker invocation gets its own **session** with unique:
- **Session ID** — Random 8-char hex (override with `TSDOCKER_SESSION_ID`)
- **Registry port** — Dynamically allocated (override with `TSDOCKER_REGISTRY_PORT`)
- **Registry container** — Named `tsdocker-registry-<sessionId>`
- **Builder suffix** — In CI, the buildx builder gets a `-<sessionId>` suffix to prevent collisions
This prevents resource conflicts when multiple CI jobs run tsdocker in parallel. Auto-detected CI systems:
| Environment Variable | CI System |
|---------------------|-----------|
| `GITEA_ACTIONS` | Gitea Actions |
| `GITHUB_ACTIONS` | GitHub Actions |
| `GITLAB_CI` | GitLab CI |
| `CI` | Generic CI |
In local dev, no suffix is added — keeping a persistent builder for faster rebuilds.
### 🔍 Docker Context & Topology Detection
tsdocker automatically detects your Docker environment topology:
| Topology | Detection | Meaning |
|----------|-----------|---------|
| `local` | Default | Standard Docker installation on the host |
| `socket-mount` | `/.dockerenv` exists | Running inside a container with Docker socket mounted |
| `dind` | `DOCKER_HOST` starts with `tcp://` | Docker-in-Docker setup |
Context-aware builder names (`tsdocker-builder-<context>`) prevent conflicts across Docker contexts. Rootless Docker configurations trigger appropriate warnings.
## Registry Authentication
### Environment Variables
@@ -213,7 +265,7 @@ export DOCKER_REGISTRY_PASSWORD="password"
### Docker Config Fallback
When pushing, tsdocker will also read credentials from `~/.docker/config.json` if no explicit credentials are provided via environment variables. This means `docker login` credentials work automatically.
When pushing, tsdocker will also read credentials from `~/.docker/config.json` if no explicit credentials are provided via environment variables. This means `docker login` credentials work automatically. Docker Hub special cases (`docker.io`, `index.docker.io`, `registry-1.docker.io`) are all recognized.
### Login Command
@@ -270,6 +322,26 @@ tsdocker discovers files matching `Dockerfile*`:
| `Dockerfile_alpine` | `alpine` |
| `Dockerfile_##version##` | Uses `package.json` version |
### 🎯 Dockerfile Filtering
Build or push only the Dockerfiles you need. Positional arguments are matched against Dockerfile basenames as glob patterns:
```bash
# Build a single Dockerfile
tsdocker build Dockerfile_base
# Glob patterns with * and ? wildcards
tsdocker build Dockerfile_app*
# Multiple patterns
tsdocker build Dockerfile_base Dockerfile_web
# Push specific images without rebuilding
tsdocker push --no-build Dockerfile_api
```
When filtering for `build`, **dependencies are auto-resolved**: if `Dockerfile_app` depends on `Dockerfile_base`, specifying only `Dockerfile_app` will automatically include `Dockerfile_base` in the build order.
### 🔗 Dependency-Aware Builds
If you have multiple Dockerfiles that depend on each other:
@@ -347,20 +419,6 @@ Use different repository names for different registries:
When pushing, tsdocker maps the local repo name to the registry-specific path. For example, a locally built `myproject:latest` becomes `registry.gitlab.com/mygroup/myproject:latest` and `docker.io/myuser/myproject:latest`.
### 🐳 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:
@@ -449,6 +507,19 @@ build-and-push:
DOCKER_REGISTRY_1: "ghcr.io|${{ github.actor }}|${{ secrets.GITHUB_TOKEN }}"
```
**Gitea Actions:**
```yaml
- name: Build and Push
run: |
npm install -g @git.zone/tsdocker
tsdocker push
env:
DOCKER_REGISTRY_1: "gitea.example.com|${{ secrets.REGISTRY_USER }}|${{ secrets.REGISTRY_PASSWORD }}"
```
tsdocker auto-detects all three CI systems and enables session isolation automatically — no extra configuration needed.
## TypeScript API
tsdocker can also be used programmatically:
@@ -458,10 +529,6 @@ import { TsDockerManager } from '@git.zone/tsdocker/dist_ts/classes.tsdockermana
import type { ITsDockerConfig } from '@git.zone/tsdocker/dist_ts/interfaces/index.js';
const config: ITsDockerConfig = {
baseImage: 'node:20',
command: 'npm test',
dockerSock: false,
keyValueObject: {},
registries: ['docker.io'],
platforms: ['linux/amd64', 'linux/arm64'],
};
@@ -472,6 +539,25 @@ await manager.build({ parallel: true });
await manager.push();
```
## Environment Variables
### CI & Session Control
| Variable | Description |
|----------|-------------|
| `TSDOCKER_SESSION_ID` | Override the auto-generated session ID (default: random 8-char hex) |
| `TSDOCKER_REGISTRY_PORT` | Override the dynamically allocated local registry port |
| `CI` | Generic CI detection (also `GITHUB_ACTIONS`, `GITLAB_CI`, `GITEA_ACTIONS`) |
### Registry Credentials
| Variable | Description |
|----------|-------------|
| `DOCKER_REGISTRY_1` through `DOCKER_REGISTRY_10` | Pipe-delimited: `registry\|username\|password` |
| `DOCKER_REGISTRY_URL` | Registry URL for single-registry setup |
| `DOCKER_REGISTRY_USER` | Username for single-registry setup |
| `DOCKER_REGISTRY_PASSWORD` | Password for single-registry setup |
## Requirements
- **Docker** — Docker Engine 20+ or Docker Desktop
@@ -507,6 +593,15 @@ tsdocker login
tsdocker also falls back to `~/.docker/config.json` — ensure you've run `docker login` for your target registries.
### Push fails with "fetch failed"
tsdocker automatically retries failed requests up to 6 times with exponential backoff. If pushes still fail:
- Check network connectivity to the target registry
- Verify your credentials haven't expired
- Look for retry log messages (`fetch failed (attempt X/6)`) to diagnose the pattern
- Large layers may need longer timeouts — the default 5-minute timeout per request should cover most cases
### Circular dependency detected
Review your Dockerfiles' `FROM` statements — you have images depending on each other in a loop.
@@ -522,16 +617,6 @@ node_modules
dist_ts
```
## 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.