134 lines
4.9 KiB
Markdown
134 lines
4.9 KiB
Markdown
# tsdocker Project Hints
|
|
|
|
## Module Purpose
|
|
|
|
tsdocker is a comprehensive Docker development and building tool. It provides:
|
|
- Testing npm modules in clean Docker environments (legacy feature)
|
|
- Building Dockerfiles with dependency ordering
|
|
- Multi-registry push/pull support
|
|
- Multi-architecture builds (amd64/arm64)
|
|
|
|
## New CLI Commands (2026-01-19)
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `tsdocker` | Run tests in container (legacy default behavior) |
|
|
| `tsdocker build` | Build all Dockerfiles with dependency ordering |
|
|
| `tsdocker push [registry]` | Push images to configured registries |
|
|
| `tsdocker pull <registry>` | Pull images from registry |
|
|
| `tsdocker test` | Run container tests (test scripts) |
|
|
| `tsdocker login` | Login to configured registries |
|
|
| `tsdocker list` | List discovered Dockerfiles and dependencies |
|
|
| `tsdocker clean --all` | Clean up Docker environment |
|
|
| `tsdocker vscode` | Start VS Code in Docker |
|
|
|
|
## Configuration
|
|
|
|
Configure in `package.json` under `@git.zone/tsdocker`:
|
|
|
|
```json
|
|
{
|
|
"@git.zone/tsdocker": {
|
|
"registries": ["registry.gitlab.com", "docker.io"],
|
|
"registryRepoMap": {
|
|
"registry.gitlab.com": "host.today/ht-docker-node"
|
|
},
|
|
"buildArgEnvMap": {
|
|
"NODE_VERSION": "NODE_VERSION"
|
|
},
|
|
"platforms": ["linux/amd64", "linux/arm64"],
|
|
"push": false,
|
|
"testDir": "./test"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Configuration Options
|
|
|
|
- `baseImage`: Base Docker image for testing (legacy)
|
|
- `command`: Command to run in container (legacy)
|
|
- `dockerSock`: Mount Docker socket (legacy)
|
|
- `registries`: Array of registry URLs to push to
|
|
- `registryRepoMap`: Map registry URLs to different repo paths
|
|
- `buildArgEnvMap`: Map Docker build ARGs to environment variables
|
|
- `platforms`: Target architectures for buildx
|
|
- `push`: Auto-push after build
|
|
- `testDir`: Directory containing test scripts
|
|
|
|
## Registry Authentication
|
|
|
|
Set environment variables for registry login:
|
|
|
|
```bash
|
|
# Pipe-delimited format (numbered 1-10)
|
|
export DOCKER_REGISTRY_1="registry.gitlab.com|username|password"
|
|
export DOCKER_REGISTRY_2="docker.io|username|password"
|
|
|
|
# Or individual registry format
|
|
export DOCKER_REGISTRY_URL="registry.gitlab.com"
|
|
export DOCKER_REGISTRY_USER="username"
|
|
export DOCKER_REGISTRY_PASSWORD="password"
|
|
```
|
|
|
|
## File Structure
|
|
|
|
```
|
|
ts/
|
|
├── index.ts (entry point)
|
|
├── tsdocker.cli.ts (CLI commands)
|
|
├── tsdocker.config.ts (configuration)
|
|
├── tsdocker.plugins.ts (plugin imports)
|
|
├── tsdocker.docker.ts (legacy test runner)
|
|
├── tsdocker.snippets.ts (Dockerfile generation)
|
|
├── classes.dockerfile.ts (Dockerfile management)
|
|
├── classes.dockerregistry.ts (registry authentication)
|
|
├── classes.registrystorage.ts (registry storage)
|
|
├── classes.tsdockermanager.ts (orchestrator)
|
|
└── interfaces/
|
|
└── index.ts (type definitions)
|
|
```
|
|
|
|
## Dependencies
|
|
|
|
- `@push.rocks/lik`: Object mapping utilities
|
|
- `@push.rocks/smartfs`: Filesystem operations
|
|
- `@push.rocks/smartshell`: Shell command execution
|
|
- `@push.rocks/smartcli`: CLI framework
|
|
- `@push.rocks/projectinfo`: Project metadata
|
|
|
|
## Parallel Builds
|
|
|
|
`--parallel` flag enables level-based parallel Docker builds:
|
|
|
|
```bash
|
|
tsdocker build --parallel # parallel, default concurrency (4)
|
|
tsdocker build --parallel=8 # parallel, concurrency 8
|
|
tsdocker build --parallel --cached # works with both modes
|
|
```
|
|
|
|
Implementation: `Dockerfile.computeLevels()` groups topologically sorted Dockerfiles into dependency levels. `Dockerfile.runWithConcurrency()` provides a worker-pool pattern for bounded concurrency. Both are public static methods on the `Dockerfile` class. The parallel logic exists in both `Dockerfile.buildDockerfiles()` (standard mode) and `TsDockerManager.build()` (cached mode).
|
|
|
|
## OCI Distribution API Push (v1.16+)
|
|
|
|
All builds now go through a persistent local registry (`localhost:5234`) with volume storage at `.nogit/docker-registry/`. Pushes use the `RegistryCopy` class (`ts/classes.registrycopy.ts`) which implements the OCI Distribution API to copy images (including multi-arch manifest lists) from the local registry to remote registries. This replaces the old `docker tag + docker push` approach that only worked for single-platform images.
|
|
|
|
Key classes:
|
|
- `RegistryCopy` — HTTP-based OCI image copy (auth, blob transfer, manifest handling)
|
|
- `Dockerfile.push()` — Now delegates to `RegistryCopy.copyImage()`
|
|
- `Dockerfile.needsLocalRegistry()` — Always returns true
|
|
- `Dockerfile.startLocalRegistry()` — Uses persistent volume mount
|
|
|
|
The `config.push` field is now a no-op (kept for backward compat).
|
|
|
|
## Build Status
|
|
|
|
- Build: ✅ Passes
|
|
- Legacy test functionality preserved
|
|
- New Docker build functionality added
|
|
|
|
## Previous Upgrades (2025-11-22)
|
|
|
|
- Updated all @git.zone/_ dependencies to @git.zone/_ scope
|
|
- Updated all @pushrocks/_ dependencies to @push.rocks/_ scope
|
|
- Migrated from smartfile v8 to smartfs v1.1.0
|