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

fix(config): update workflow repository URL handling and package config file references

Browse Source
This commit is contained in:
Jürgen Kunz
2026-03-24 17:00:15 +00:00
parent 3a4d510304
commit 7af0c59708
9 changed files with 147 additions and 102 deletions
Download Patch File Download Diff File Expand all files Collapse all files

170
readme.md
View File

@@ -44,6 +44,7 @@ tsdocker build
```
tsdocker will:
1. 🔍 Discover all `Dockerfile*` files in your project
2. 📊 Analyze `FROM` dependencies between them
3. 🔄 Sort them topologically
@@ -84,64 +85,64 @@ tsdocker push --no-build Dockerfile_api Dockerfile_web
## CLI Commands
| Command | Description |
|---------|-------------|
| `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 |
| `tsdocker test` | Build + run container test scripts (`test_*.sh`) |
| `tsdocker login` | Authenticate with configured registries |
| `tsdocker list` | Display discovered Dockerfiles and their dependencies |
| `tsdocker config` | Manage global tsdocker configuration (remote builders, etc.) |
| `tsdocker clean` | Interactively clean Docker environment |
| Command | Description |
| -------------------------- | ------------------------------------------------------------ |
| `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 |
| `tsdocker test` | Build + run container test scripts (`test_*.sh`) |
| `tsdocker login` | Authenticate with configured registries |
| `tsdocker list` | Display discovered Dockerfiles and their dependencies |
| `tsdocker config` | Manage global tsdocker configuration (remote builders, etc.) |
| `tsdocker clean` | Interactively clean Docker environment |
### 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 |
| `--cached` | Skip unchanged Dockerfiles (content-hash based) |
| `--verbose` | Stream raw `docker build` output |
| `--parallel` | Enable level-based parallel builds (default concurrency: 4) |
| `--parallel=8` | Parallel builds with custom concurrency |
| `--context=mycontext` | Use a specific Docker context |
| 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 |
| `--cached` | Skip unchanged Dockerfiles (content-hash based) |
| `--verbose` | Stream raw `docker build` output |
| `--parallel` | Enable level-based parallel builds (default concurrency: 4) |
| `--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 |
| 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 |
### Config Subcommands
| Subcommand | Description |
|------------|-------------|
| `add-builder` | Add or update a remote builder node |
| `remove-builder` | Remove a remote builder by name |
| `list-builders` | List all configured remote builders |
| `show` | Show the full global configuration |
| Subcommand | Description |
| ---------------- | ----------------------------------- |
| `add-builder` | Add or update a remote builder node |
| `remove-builder` | Remove a remote builder by name |
| `list-builders` | List all configured remote builders |
| `show` | Show the full global configuration |
**`add-builder` flags:**
| Flag | Description |
|------|-------------|
| `--name=<name>` | Builder name (e.g. `arm64-builder`) |
| `--host=<user@ip>` | SSH host (e.g. `armbuilder@192.168.1.100`) |
| `--platform=<p>` | Target platform (e.g. `linux/arm64`) |
| Flag | Description |
| ------------------ | --------------------------------------------------------- |
| `--name=<name>` | Builder name (e.g. `arm64-builder`) |
| `--host=<user@ip>` | SSH host (e.g. `armbuilder@192.168.1.100`) |
| `--platform=<p>` | Target platform (e.g. `linux/arm64`) |
| `--ssh-key=<path>` | SSH key path (optional, uses SSH agent/config by default) |
### Clean Flags
| Flag | Description |
|------|-------------|
| Flag | Description |
| ------- | -------------------------------------------------- |
| `--all` | Include all images and volumes (not just dangling) |
| `-y` | Auto-confirm all prompts |
| `-y` | Auto-confirm all prompts |
## Configuration
@@ -167,13 +168,13 @@ Configure tsdocker in your `package.json` or `npmextra.json` under the `@git.zon
#### Build & Push Options
| Option | Type | Default | 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[]` | `["linux/amd64"]` | Target architectures for multi-arch builds |
| `testDir` | `string` | `./test` | Directory containing test scripts |
| Option | Type | Default | 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[]` | `["linux/amd64"]` | Target architectures for multi-arch builds |
| `testDir` | `string` | `./test` | Directory containing test scripts |
## Architecture: How tsdocker Works
@@ -217,12 +218,12 @@ tsdocker uses a **local OCI registry** as the canonical store for all built imag
### 🔑 Why a Local Registry?
| Problem | Solution |
|---------|----------|
| `docker buildx --load` fails for multi-arch images | `buildx --push` to local registry works for any number of platforms |
| `docker push` only pushes single-platform manifests | OCI API copy preserves full manifest lists (multi-arch) |
| 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 |
| Problem | Solution |
| --------------------------------------------------- | ------------------------------------------------------------------- |
| `docker buildx --load` fails for multi-arch images | `buildx --push` to local registry works for any number of platforms |
| `docker push` only pushes single-platform manifests | OCI API copy preserves full manifest lists (multi-arch) |
| 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
@@ -246,12 +247,12 @@ Every tsdocker invocation gets its own **session** with unique:
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 |
| 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.
@@ -259,11 +260,11 @@ In local dev, no suffix is added — keeping a persistent builder for faster reb
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 |
| 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.
@@ -309,6 +310,7 @@ Build for multiple platforms using Docker Buildx:
```
tsdocker automatically:
- Sets up a Buildx builder with `--driver-opt network=host` (so buildx can reach the local registry)
- Pushes multi-platform images to the local registry via `buildx --push`
- Copies the full manifest list (including all platform variants) to remote registries on `tsdocker push`
@@ -354,6 +356,7 @@ When remote builders are configured and the project's `platforms` includes a mat
```
**Prerequisites for the remote machine:**
- Docker installed and running
- A user with Docker group access (no sudo needed)
- SSH key access configured
@@ -379,11 +382,11 @@ tsdocker groups Dockerfiles into **dependency levels** using topological analysi
tsdocker discovers files matching `Dockerfile*`:
| File Name | Version Tag |
|-----------|-------------|
| `Dockerfile` | `latest` |
| `Dockerfile_v1.0.0` | `v1.0.0` |
| `Dockerfile_alpine` | `alpine` |
| File Name | Version Tag |
| ------------------------ | --------------------------- |
| `Dockerfile` | `latest` |
| `Dockerfile_v1.0.0` | `v1.0.0` |
| `Dockerfile_alpine` | `alpine` |
| `Dockerfile_##version##` | Uses `package.json` version |
### 🎯 Dockerfile Filtering
@@ -492,6 +495,7 @@ tsdocker list
```
Output:
```
Discovered Dockerfiles:
========================
@@ -556,7 +560,7 @@ build-and-push:
- npm install -g @git.zone/tsdocker
- tsdocker push
variables:
DOCKER_REGISTRY_1: "registry.gitlab.com|$CI_REGISTRY_USER|$CI_REGISTRY_PASSWORD"
DOCKER_REGISTRY_1: 'registry.gitlab.com|$CI_REGISTRY_USER|$CI_REGISTRY_PASSWORD'
```
**GitHub Actions:**
@@ -568,7 +572,7 @@ build-and-push:
tsdocker login
tsdocker push
env:
DOCKER_REGISTRY_1: "ghcr.io|${{ github.actor }}|${{ secrets.GITHUB_TOKEN }}"
DOCKER_REGISTRY_1: 'ghcr.io|${{ github.actor }}|${{ secrets.GITHUB_TOKEN }}'
```
**Gitea Actions:**
@@ -579,7 +583,7 @@ build-and-push:
npm install -g @git.zone/tsdocker
tsdocker push
env:
DOCKER_REGISTRY_1: "gitea.example.com|${{ secrets.REGISTRY_USER }}|${{ secrets.REGISTRY_PASSWORD }}"
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.
@@ -607,20 +611,20 @@ await manager.push();
### 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`) |
| 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 |
|----------|-------------|
| 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 |
| `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