CATLX — Docker Architecture
This skill owns the container isolation and deployment layer for heavy ML workloads, enterprise
multi-service deployments, and portable runtime packages. On Windows this is Docker Desktop with a WSL2
backend. Docker is not required for T0/T1 operation — all capabilities are available without it there.
Canonical detail: ../knowledge/references/docker.md. Fragment template:
../templates/docker-compose.fragment.yml. Load on demand.
Purpose
Isolate heavy workloads (LLM, Whisper, TTS, OCR, ChromaDB, browser, telemetry) and deploy CATLX services
portably with relocatable volumes and GPU passthrough.
When to activate
- User asks how CATLX uses containers, or which services run in containers.
- Writing/reading the Compose file, debugging a container crash/degradation, or offline mode.
- Enterprise deployment (Swarm/Kubernetes).
What this skill handles
- Container strategy — Docker for heavy ML/enterprise/portable packages; optional for T0/T1; preferred
on T2+ (or when Docker Desktop is present) for isolation.
- Core service containers —
catlx-core, catlx-llm-server, catlx-whisper, catlx-tts,
catlx-chromadb, catlx-browser, catlx-ocr, catlx-telemetry (GPU passthrough where relevant).
- Docker Compose configuration —
/docker/docker-compose.yml defines services, build contexts, volume
mounts, network config, GPU assignments, health checks, restart policies; docker-compose.override.yml for
per-machine customization.
- Portable containers & relocatable volumes — all volume mount points relative to
CATLX_ROOT; resolves
when moved to a new machine (internal → external NVMe SSD); image builder embeds a portable image registry
so images load without internet.
- Offline mode — triggered automatically on network-health-check failure; remote providers disabled, local
LLM servers serve all inference, marketplace browseable from cache, memory/workflow continue; on
reconnection auto-resume + sync queued ops.
- Enterprise (Docker Swarm & Kubernetes) — distribute services across nodes (LLM/OCR on GPU nodes, core/
telemetry on CPU nodes); Helm chart with Kubernetes-native health checks, HPA for inference, PVCs for data.
- Docker recovery —
restart: unless-stopped; container health monitoring; failure to become healthy →
mark capability degraded, route to fallbacks, surface 'Service Degraded'; full stack restart via dashboard
or voice "Restart CATLX services."
Requirements / constraints
- R10 (local-first/offline): must run fully functional without internet.
- R5: containers are the strictest plugin/agent sandbox tier (T2+).
- Windows: Docker Desktop + WSL2 backend; GPU passthrough for CUDA workloads (see
../knowledge/rules/windows-rules.md).
- Volumes relative to
CATLX_ROOT (portability, R3/R11).
Canonical knowledge it reads
../knowledge/references/docker.md · ../knowledge/rules/windows-rules.md ·
../knowledge/references/portability.md · ../knowledge/references/data-registries.md.
Delegation
- Which tier / container or fallback → delegate to
catlx-capability-routing
(skill({ name: "catlx-capability-routing" })).
- Container crash recovery → delegate to
catlx-recovery
(skill({ name: "catlx-recovery" })).
- Relocatable volume paths / portable registry → delegate to
catlx-portability
(skill({ name: "catlx-portability" })).
- Container sandbox security → delegate to
catlx-security
(skill({ name: "catlx-security" })).
- Containerized modules (SILEXIS packaging) → delegate to
catlx-silexis-modules
(skill({ name: "catlx-silexis-modules" })).
Edge cases & warnings
- Not required on T0/T1 — do not assume Docker is present; fall back to local process/subprocess.
- GPU passthrough — only on GPU-capable hosts; otherwise drop to CPU.
- Offline — never depend on remote provider/container registry when offline; use the portable registry +
local servers.
- Container health — a container that never becomes healthy marks the capability degraded and routes to
fallbacks; surface the alert.
Component lifecycle policy (reuse → install → adapt → create)
NEVER create a new component as the default. Before building/creating anything (a sub-skill, dependency,
reference, workflow, helper, adapter, or template), check, in order:
- Reuse an existing local component (resolve aliases/equivalent capabilities first) — reuse, don't rebuild.
- Use an already-registered component from the registry.
- Install a suitable existing, trusted, supported component → validate → register → connect to the graph → use.
- Adapt an existing compatible component via a small persistent adapter/wrapper instead of re-creating it.
- Create only as last resort — then make it permanent immediately: stable id, canonical location, register,
add to the capability index + dependency graph, add provenance, use, and allow future reuse.
- Never reorganise/recreate already-generated components (no
Skill X 2 / new / temp variants); extend the
existing one. Never create a second competing knowledge source; connect back to the canonical knowledge/ layer.
Promote any reusable artifact out of /tmp/scratch into the permanent ecosystem.
Full policy: ../knowledge/rules/component-lifecycle.md.
Source / provenance
- Source: PART XIV §14.1–14.7 (container strategy, core service containers, Compose config, portable
containers & relocatable volumes, offline mode, Swarm/Kubernetes, Docker recovery).
- Inferred/adapted: Windows Docker Desktop + WSL2 backend; USB-drive wording removed from relocatable
volume/portable-registry discussion (external NVMe SSD only).
1---2> Mirror copy of `skills\catlx-core\catlx-docker\SKILL.md` (canonical content lives in `catlx-core`). Kept at the repository root only for registry-path compatibility. Edit the canonical copy, not this file.3name: catlx-docker4description: "Handles the CATLX Docker architecture: the container strategy, core service containers, Docker Compose configuration with overrides, portable/relocatable volumes relative to CATLX_ROOT, offline mode, Docker Swarm/Kubernetes for enterprise, and Docker recovery or service degradation. Use when the user asks about CATLX Docker/containers, the Compose file, GPU containers, offline containers, relocatable volumes, Swarm/Kubernetes, or container health/restart."5metadata:6 catlx: subsystem7 category: infrastructure8 subsystem: Docker_Layer9 capability: container-deployment10 version: "1.0.0"11 source: https://skillmd.com/skills/samraddhashrivastavatech/catlx-docker12 upstream: "PART XIV §14.1-14.7"13 aliases: "docker, containers, compose, containerized, gpu containers, swarm, kubernetes"14 depends-on: "catlx-hardware-adaptation"15---1617# CATLX — Docker Architecture1819This skill owns the **container isolation and deployment layer** for heavy ML workloads, enterprise20multi-service deployments, and portable runtime packages. On Windows this is **Docker Desktop with a WSL221backend**. Docker is **not required** for T0/T1 operation — all capabilities are available without it there.2223> Canonical detail: `../knowledge/references/docker.md`. Fragment template:24> `../templates/docker-compose.fragment.yml`. Load on demand.2526---2728## Purpose2930Isolate heavy workloads (LLM, Whisper, TTS, OCR, ChromaDB, browser, telemetry) and deploy CATLX services31portably with relocatable volumes and GPU passthrough.3233## When to activate3435- User asks how CATLX uses containers, or which services run in containers.36- Writing/reading the Compose file, debugging a container crash/degradation, or offline mode.37- Enterprise deployment (Swarm/Kubernetes).3839## What this skill handles40411. **Container strategy** — Docker for heavy ML/enterprise/portable packages; optional for T0/T1; preferred42 on T2+ (or when Docker Desktop is present) for isolation.432. **Core service containers** — `catlx-core`, `catlx-llm-server`, `catlx-whisper`, `catlx-tts`,44 `catlx-chromadb`, `catlx-browser`, `catlx-ocr`, `catlx-telemetry` (GPU passthrough where relevant).453. **Docker Compose configuration** — `/docker/docker-compose.yml` defines services, build contexts, volume46 mounts, network config, GPU assignments, health checks, restart policies; `docker-compose.override.yml` for47 per-machine customization.484. **Portable containers & relocatable volumes** — all volume mount points relative to `CATLX_ROOT`; resolves49 when moved to a new machine (internal → external NVMe SSD); image builder embeds a portable image registry50 so images load without internet.515. **Offline mode** — triggered automatically on network-health-check failure; remote providers disabled, local52 LLM servers serve all inference, marketplace browseable from cache, memory/workflow continue; on53 reconnection auto-resume + sync queued ops.546. **Enterprise (Docker Swarm & Kubernetes)** — distribute services across nodes (LLM/OCR on GPU nodes, core/55 telemetry on CPU nodes); Helm chart with Kubernetes-native health checks, HPA for inference, PVCs for data.567. **Docker recovery** — `restart: unless-stopped`; container health monitoring; failure to become healthy →57 mark capability degraded, route to fallbacks, surface 'Service Degraded'; full stack restart via dashboard58 or voice "Restart CATLX services."5960## Requirements / constraints6162- **R10 (local-first/offline):** must run fully functional without internet.63- **R5:** containers are the strictest plugin/agent sandbox tier (T2+).64- Windows: Docker Desktop + WSL2 backend; GPU passthrough for CUDA workloads (see `../knowledge/rules/windows-rules.md`).65- Volumes relative to `CATLX_ROOT` (portability, R3/R11).6667## Canonical knowledge it reads6869`../knowledge/references/docker.md` · `../knowledge/rules/windows-rules.md` ·70`../knowledge/references/portability.md` · `../knowledge/references/data-registries.md`.7172## Delegation7374- **Which tier / container or fallback** → delegate to `catlx-capability-routing`75 (`skill({ name: "catlx-capability-routing" })`).76- **Container crash recovery** → delegate to `catlx-recovery`77 (`skill({ name: "catlx-recovery" })`).78- **Relocatable volume paths / portable registry** → delegate to `catlx-portability`79 (`skill({ name: "catlx-portability" })`).80- **Container sandbox security** → delegate to `catlx-security`81 (`skill({ name: "catlx-security" })`).82- **Containerized modules (SILEXIS packaging)** → delegate to `catlx-silexis-modules`83 (`skill({ name: "catlx-silexis-modules" })`).8485## Edge cases & warnings8687- **Not required on T0/T1** — do not assume Docker is present; fall back to local process/subprocess.88- **GPU passthrough** — only on GPU-capable hosts; otherwise drop to CPU.89- **Offline** — never depend on remote provider/container registry when offline; use the portable registry +90 local servers.91- **Container health** — a container that never becomes healthy marks the capability degraded and routes to92 fallbacks; surface the alert.9394## Component lifecycle policy (reuse → install → adapt → create)9596**NEVER create a new component as the default.** Before building/creating anything (a sub-skill, dependency,97reference, workflow, helper, adapter, or template), check, in order:981. **Reuse** an existing local component (resolve aliases/equivalent capabilities first) — reuse, don't rebuild.992. **Use** an already-registered component from the registry.1003. **Install** a suitable existing, trusted, supported component → validate → register → connect to the graph → use.1014. **Adapt** an existing compatible component via a small persistent adapter/wrapper instead of re-creating it.1025. **Create only as last resort** — then make it permanent immediately: stable id, canonical location, register,103 add to the capability index + dependency graph, add provenance, use, and allow future reuse.1046. Never reorganise/recreate already-generated components (no `Skill X 2` / `new` / `temp` variants); extend the105 existing one. Never create a second competing knowledge source; connect back to the canonical `knowledge/` layer.106 Promote any reusable artifact out of `/tmp`/scratch into the permanent ecosystem.107108> Full policy: `../knowledge/rules/component-lifecycle.md`.109110## Source / provenance111112- **Source:** PART XIV §14.1–14.7 (container strategy, core service containers, Compose config, portable113 containers & relocatable volumes, offline mode, Swarm/Kubernetes, Docker recovery).114- **Inferred/adapted:** Windows Docker Desktop + WSL2 backend; USB-drive wording removed from relocatable115 volume/portable-registry discussion (external NVMe SSD only).