Skip to content

CLAUDE.md

Latest commit

 

History

History
43 lines (27 loc) · 3.35 KB

CLAUDE.md

File metadata and controls

43 lines (27 loc) · 3.35 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

@iobroker/plugin-docker is an ioBroker plugin that manages Docker containers declared via Docker Compose files. It parses Compose YAML/JSON/JSON5 files, substitutes adapter config values using template variables (${config.path} or ${config_path}), converts them into ContainerConfig objects, and manages container lifecycle via the Docker API (using dockerode).

Build & Development Commands

npm run build        # TypeScript compile → build/esm, then esm2cjs → build/cjs, then tasks.js copies types/package.json
npm run lint         # ESLint with @iobroker/eslint-config
npm test             # Integration tests via mocha (requires build first: tests import from build/cjs)

Architecture

The plugin has a pipeline: Compose file → parsed structure → ContainerConfig[] → Docker API calls.

  • src/index.ts — DockerPlugin (extends PluginBase). Entry point. Reads Compose files (YAML/JSON/JSON5), applies template substitution, converts to ContainerConfig[], and initializes DockerManagerOfOwnContainers.
  • src/lib/parseDockerCompose.ts — Parses raw YAML into a typed ComposeTop structure (services, networks, volumes).
  • src/lib/compose2config.ts — Converts ComposeTop into an array of ContainerConfig objects, mapping Compose fields to the internal normalized format.
  • src/lib/templates.ts — Template engine for variable substitution. Supports ${config.path:-default}, ${config_path:-default}, {{config.path}}, and ${instance}. Walks an entire config tree recursively.
  • src/lib/DockerManager.ts — Low-level Docker operations using dockerode. Handles container CRUD, image pull, network/volume management, stats monitoring, file operations on volumes, and SSH tunneling.
  • src/lib/DockerManagerOfOwnContainers.ts — Higher-level orchestrator (extends DockerManager). Compares desired vs. existing container state, creates/recreates containers as needed, handles volume copy provisioning, monitoring, and graceful stop on unload.
  • src/types.d.ts — All shared TypeScript interfaces (ContainerConfig, DockerContainerInspect, ContainerInfo, etc.).

Dual-format Publishing

The package ships both ESM (build/esm/) and CJS (build/cjs/). The postbuild script uses esm2cjs for conversion, then tasks.js copies types.d.ts and package.json into both output dirs and patches the CJS index.js to add module.exports compatibility.

Testing

Tests are in test/ and run against the CJS build output. You must npm run build before running npm test. Test fixtures are test/docker-compose-*.yaml files with sample Compose configurations.

ioBroker-Specific Labels

Compose services use custom labels (prefixed iob) to control plugin behavior: iobEnabled, iobStopOnUnload, iobAutoImageUpdate, iobMonitoringEnabled, iobWaitForReady, iobBackup, iobCopyVolumes. These are extracted during composeToContainerConfigs and become fields on ContainerConfig.

Naming Conventions

Container names, volume names, and network names are prefixed with iob_<adapterName>_<instance>_ to avoid collisions. Network named true maps to the default shared network iob_<adapterName>_<instance>. Network named iobroker is used as-is.