n8n-nodes-docker-api 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2022 n8n
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,278 @@
+![n8n Docker Node](./assets/banner.png)
+
+# 🐳 n8n-nodes-docker-api
+
+![npm](https://img.shields.io/npm/v/n8n-nodes-docker-api)
+![License](https://img.shields.io/npm/l/n8n-nodes-docker-api)
+
+> Interact with Docker via direct API (no Portainer required) — manage containers, stream logs, and automate infrastructure with ease.
+
+---
+
+## ✨ Why this node?
+
+Managing Docker via raw HTTP calls in n8n is painful and error-prone.
+
+This node gives you:
+
+* 🔍 **Clean container listing** (normalized output)
+* 📜 **Readable logs** (stdout/stderr separated, no binary noise)
+* ⚡ **Simple control** (start/stop containers safely)
+* 🔐 **Built-in access control** (read-only vs full control)
+
+👉 Turn Docker into a **first-class automation tool inside n8n**
+
+---
+
+## 🚀 Quick Start
+
+1. Install the node:
+
+```bash
+npm install n8n-nodes-docker-api
+```
+
+2. Add **Docker API credentials**
+3. Add the **Docker node** to your workflow
+4. Choose an operation and execute
+
+✅ No manual API calls needed
+
+---
+
+## 📦 Installation
+
+### Community Nodes (Recommended)
+
+1. Go to **Settings → Community Nodes**
+2. Install: `n8n-nodes-docker-api`
+
+---
+
+### Manual Installation
+
+```bash
+npm install n8n-nodes-docker-api
+```
+
+---
+
+## 🧪 Usage
+
+### Docker Node in n8n
+
+![Docker Node UI](./assets/node-ui.png)
+
+1. Add the **Docker node**
+2. Select an operation:
+
+   * List Containers
+   * Get Container Logs
+   * Start Container
+   * Stop Container
+3. Configure credentials
+4. Execute the node
+
+---
+
+### Example: List Containers
+
+* Operation: `List Containers`
+* Optional filters:
+
+  * Name
+  * Status
+  * Show all containers
+
+---
+
+## 🔐 Credentials
+
+### Credentials UI in n8n
+
+![Docker Credentials UI](./assets/credentials-ui.png)
+
+---
+
+### Connection Modes
+
+#### 🟢 Unix Socket (Local)
+
+* Default for local Docker setups
+* Path: `/var/run/docker.sock`
+
+---
+
+#### 🌐 TCP (Remote)
+
+* Connect to remote Docker daemon
+* Example:
+
+  * Host: `192.168.1.10`
+  * Port: `2375`
+
+⚠️ Requires Docker daemon configured with:
+
+```bash
+-H tcp://0.0.0.0:2375
+```
+
+---
+
+#### 🔒 TLS (Coming in v2)
+
+* Secure remote connection using certificates
+
+---
+
+### Access Modes
+
+#### 🟡 Read Only (Recommended)
+
+* ✅ List containers
+* ✅ Get logs
+* ❌ Cannot start/stop containers
+
+---
+
+#### 🔴 Full Control
+
+* ✅ All operations enabled
+
+---
+
+## 📋 Supported Operations (v1)
+
+| Operation          | Description                             | Access       |
+| ------------------ | --------------------------------------- | ------------ |
+| List Containers    | Get containers with normalized output   | Read Only    |
+| Get Container Logs | Logs with stream filtering & timestamps | Read Only    |
+| Start Container    | Start stopped containers                | Full Control |
+| Stop Container     | Stop running containers (with dry run)  | Full Control |
+
+---
+
+## 🔥 Real Use Cases
+
+### ♻️ Self-Healing Containers
+
+Automatically restart crashed services:
+
+```
+List Containers → IF (status != running) → Start Container
+```
+
+---
+
+### 🚨 Log-Based Alerting
+
+Detect errors and notify:
+
+```
+Get Logs → Search "ERROR" → Send Slack alert
+```
+
+---
+
+### 📊 Container Monitoring
+
+Track system health:
+
+```
+Schedule → List Containers → Aggregate → Report
+```
+
+---
+
+## 🧠 Output Examples
+
+### List Containers
+
+```json
+{
+  "id": "3025272c7592...",
+  "shortId": "3025272c7592",
+  "name": "qdrant",
+  "image": "qdrant/qdrant",
+  "status": "running",
+  "createdAt": "2026-03-13T23:19:38.000Z"
+}
+```
+
+---
+
+### Logs
+
+```json
+{
+  "message": "Server started",
+  "stream": "stdout"
+}
+```
+
+---
+
+## 🔒 Security
+
+⚠️ Docker access = **host-level control**
+
+### Best Practices
+
+* Use **Read Only mode** unless needed
+* Avoid exposing Docker over public TCP
+* Use a proxy like:
+
+  * `tecnativa/docker-socket-proxy`
+* Restrict network access
+
+---
+
+## 🧪 Testing
+
+```bash
+npm test
+```
+
+---
+
+## 🗺️ Roadmap
+
+### v2
+
+* Restart Container
+* Remove Container
+* Image operations (list/pull/remove)
+* TLS support
+* Container autocomplete
+
+### v3
+
+* Run container (ephemeral jobs)
+* Execute commands in container
+* Container stats
+
+### v4
+
+* Docker Trigger node (events)
+
+---
+
+## ⭐ Contributing
+
+PRs and ideas are welcome — especially for new operations and improvements.
+
+---
+
+## 📄 License
+
+MIT
+
+---
+
+## 💬 Support
+
+Open an issue on GitHub for:
+
+* Bugs
+* Feature requests
+* Questions

package/dist/credentials/DockerApi.credentials.d.ts

@@ -0,0 +1,7 @@
+import { ICredentialType, INodeProperties } from 'n8n-workflow';
+export declare class DockerApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    documentationUrl: string;
+    properties: INodeProperties[];
+}

package/dist/credentials/DockerApi.credentials.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DockerApi = void 0;
+class DockerApi {
+    constructor() {
+        this.name = 'dockerApi';
+        this.displayName = 'Docker API';
+        this.documentationUrl = 'https://github.com/YOUR_USERNAME/n8n-nodes-docker';
+        this.properties = [
+            {
+                displayName: 'Connection Mode',
+                name: 'authMode',
+                type: 'options',
+                options: [
+                    {
+                        name: 'Unix Socket (Local)',
+                        value: 'socket',
+                        description: 'Connect to Docker via local Unix socket',
+                    },
+                    {
+                        name: 'TCP (Remote)',
+                        value: 'tcp',
+                        description: 'Connect to a remote Docker daemon over TCP',
+                    },
+                    {
+                        name: 'TLS (Secure Remote)',
+                        value: 'tls',
+                        description: 'Connect to a remote Docker daemon with TLS authentication',
+                    },
+                ],
+                default: 'socket',
+            },
+            // --- Socket mode fields ---
+            {
+                displayName: 'Socket Path',
+                name: 'socketPath',
+                type: 'string',
+                default: '/var/run/docker.sock',
+                displayOptions: { show: { authMode: ['socket'] } },
+                description: 'Path to the Docker Unix socket',
+            },
+            // --- TCP mode fields ---
+            {
+                displayName: 'Host',
+                name: 'host',
+                type: 'string',
+                default: '',
+                placeholder: '192.168.1.100',
+                displayOptions: { show: { authMode: ['tcp', 'tls'] } },
+                description: 'IP address or hostname of the Docker host',
+            },
+            {
+                displayName: 'Port',
+                name: 'port',
+                type: 'number',
+                default: 2375,
+                displayOptions: { show: { authMode: ['tcp'] } },
+                description: 'Docker daemon TCP port (default: 2375)',
+            },
+            // --- TLS mode fields (v2 implementation, schema defined now) ---
+            {
+                displayName: 'TLS Port',
+                name: 'tlsPort',
+                type: 'number',
+                default: 2376,
+                displayOptions: { show: { authMode: ['tls'] } },
+                description: 'Docker daemon TLS port (default: 2376)',
+            },
+            {
+                displayName: 'CA Certificate',
+                name: 'ca',
+                type: 'string',
+                typeOptions: { rows: 4 },
+                default: '',
+                displayOptions: { show: { authMode: ['tls'] } },
+                description: 'TLS CA certificate (PEM format)',
+            },
+            {
+                displayName: 'Client Certificate',
+                name: 'cert',
+                type: 'string',
+                typeOptions: { rows: 4 },
+                default: '',
+                displayOptions: { show: { authMode: ['tls'] } },
+                description: 'TLS client certificate (PEM format)',
+            },
+            {
+                displayName: 'Client Key',
+                name: 'clientKey',
+                type: 'string',
+                typeOptions: { rows: 4, password: true },
+                default: '',
+                displayOptions: { show: { authMode: ['tls'] } },
+                description: 'TLS client private key (PEM format)',
+            },
+            // --- Access control ---
+            {
+                displayName: 'Access Mode',
+                name: 'accessMode',
+                type: 'options',
+                options: [
+                    {
+                        name: 'Read Only',
+                        value: 'readonly',
+                        description: 'Only list and inspect operations are allowed',
+                    },
+                    {
+                        name: 'Full Control',
+                        value: 'full',
+                        description: 'All operations including start, stop, and remove are allowed',
+                    },
+                ],
+                default: 'readonly',
+                description: 'Controls which operations this credential permits',
+            },
+            {
+                displayName: '',
+                name: 'securityNotice',
+                type: 'notice',
+                default: '⚠️ This credential connects to the Docker daemon. Full Control mode grants the ability to start, stop, and remove containers. Use Read Only mode unless write access is explicitly required.',
+            },
+        ];
+    }
+}
+exports.DockerApi = DockerApi;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { Docker } from './nodes/Docker/Docker.node';
+export declare const nodeTypes: (typeof Docker)[];

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodeTypes = void 0;
+const Docker_node_1 = require("./nodes/Docker/Docker.node");
+exports.nodeTypes = [Docker_node_1.Docker];

package/dist/nodes/Docker/Docker/docker.svg

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" viewBox="0 0 340 268">
+  <!-- Generator: Adobe Illustrator 30.1.0, SVG Export Plug-In . SVG Version: 2.1.1 Build 136)  -->
+  <defs>
+    <style>
+      .st0 {
+        fill: none;
+      }
+
+      .st1 {
+        fill: #2560ff;
+      }
+
+      .st2 {
+        clip-path: url(#clippath);
+      }
+    </style>
+    <clipPath id="clippath">
+      <rect class="st0" width="339.5" height="268"/>
+    </clipPath>
+  </defs>
+  <g class="st2">
+    <path class="st1" d="M334,110.1c-8.3-5.6-30.2-8-46.1-3.7-.9-15.8-9-29.2-24-40.8l-5.5-3.7-3.7,5.6c-7.2,11-10.3,25.7-9.2,39,.8,8.2,3.7,17.4,9.2,24.1-20.7,12-39.8,9.3-124.3,9.3H0c-.4,19.1,2.7,55.8,26,85.6,2.6,3.3,5.4,6.5,8.5,9.6,19,19,47.6,32.9,90.5,33,65.4,0,121.4-35.3,155.5-120.8,11.2.2,40.8,2,55.3-26,.4-.5,3.7-7.4,3.7-7.4l-5.5-3.7h0ZM85.2,92.7h-36.7v36.7h36.7v-36.7ZM132.6,92.7h-36.7v36.7h36.7v-36.7ZM179.9,92.7h-36.7v36.7h36.7v-36.7ZM227.3,92.7h-36.7v36.7h36.7v-36.7ZM37.8,92.7H1.1v36.7h36.7v-36.7ZM85.2,46.3h-36.7v36.7h36.7v-36.7ZM132.6,46.3h-36.7v36.7h36.7v-36.7ZM179.9,46.3h-36.7v36.7h36.7v-36.7ZM179.9,0h-36.7v36.7h36.7V0Z"/>
+  </g>
+</svg>

package/dist/nodes/Docker/Docker.node.d.ts

@@ -0,0 +1,5 @@
+import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class Docker implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}

package/dist/nodes/Docker/Docker.node.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Docker = void 0;
+const n8n_workflow_1 = require("n8n-workflow");
+const dockerClient_1 = require("../../utils/dockerClient");
+const descriptions_1 = require("./descriptions");
+const actions_1 = require("./actions");
+const accessGuard_1 = require("./helpers/accessGuard");
+class Docker {
+    constructor() {
+        this.description = {
+            displayName: 'Docker API',
+            name: 'docker',
+            icon: 'file:docker.svg',
+            group: ['transform'],
+            version: 1,
+            subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
+            description: 'Interact with Docker via direct API (no Portainer required)',
+            defaults: {
+                name: 'Docker API',
+            },
+            inputs: ['main'],
+            outputs: ['main'],
+            credentials: [
+                {
+                    name: 'dockerApi',
+                    required: true,
+                },
+            ],
+            properties: [
+                {
+                    displayName: 'Resource',
+                    name: 'resource',
+                    type: 'options',
+                    noDataExpression: true,
+                    options: [
+                        {
+                            name: 'Container',
+                            value: 'container',
+                        },
+                    ],
+                    default: 'container',
+                },
+                ...descriptions_1.containerOperations,
+                ...descriptions_1.containerFields,
+            ],
+        };
+    }
+    async execute() {
+        const items = this.getInputData();
+        const credentials = await this.getCredentials('dockerApi');
+        const resource = this.getNodeParameter('resource', 0);
+        const operation = this.getNodeParameter('operation', 0);
+        (0, accessGuard_1.enforceAccessMode)(credentials, operation);
+        const docker = (0, dockerClient_1.createDockerClient)(credentials);
+        const returnData = [];
+        for (let i = 0; i < items.length; i++) {
+            try {
+                const result = await actions_1.executeContainerOperation.call(this, docker, operation, i);
+                returnData.push(...result);
+            }
+            catch (error) {
+                if (this.continueOnFail()) {
+                    returnData.push({ json: { error: error.message }, pairedItem: i });
+                    continue;
+                }
+                throw new n8n_workflow_1.NodeOperationError(this.getNode(), error, { itemIndex: i });
+            }
+        }
+        return [returnData];
+    }
+}
+exports.Docker = Docker;

package/dist/nodes/Docker/actions/container/getLogs.operation.d.ts

@@ -0,0 +1,3 @@
+import Docker from 'dockerode';
+import { IExecuteFunctions } from 'n8n-workflow';
+export declare function getContainerLogs(this: IExecuteFunctions, docker: Docker, itemIndex: number): Promise<any>;

package/dist/nodes/Docker/actions/container/getLogs.operation.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getContainerLogs = getContainerLogs;
+const errorHandler_1 = require("../../helpers/errorHandler");
+const resolveContainer_1 = require("../../helpers/resolveContainer");
+/**
+ * Demultiplexes Docker log buffer format.
+ * Docker logs use an 8-byte header: [stream type (1 byte)][0,0,0,0][size (4 bytes)][payload]
+ * Stream type: 1 = stdout, 2 = stderr
+ */
+function demuxDockerLogs(buffer) {
+    const logs = [];
+    let offset = 0;
+    while (offset < buffer.length) {
+        // Need at least 8 bytes for header
+        if (offset + 8 > buffer.length) {
+            break;
+        }
+        const streamType = buffer[offset];
+        // Bytes 1-4 are zeros
+        // Bytes 5-8 are the payload size (big-endian uint32)
+        const payloadSize = buffer.readUInt32BE(offset + 4);
+        // Validate we have enough data for the payload
+        if (offset + 8 + payloadSize > buffer.length) {
+            break;
+        }
+        const payload = buffer.slice(offset + 8, offset + 8 + payloadSize);
+        const message = payload.toString('utf8');
+        // Split message into lines and add each line separately
+        const lines = message.split('\n').filter((line) => line.length > 0);
+        for (const line of lines) {
+            logs.push({
+                message: line,
+                stream: streamType === 1 ? 'stdout' : 'stderr',
+            });
+        }
+        offset += 8 + payloadSize;
+    }
+    return logs;
+}
+async function getContainerLogs(docker, itemIndex) {
+    try {
+        const containerId = this.getNodeParameter('containerId', itemIndex);
+        const tail = this.getNodeParameter('tail', itemIndex, 100);
+        const timestamps = this.getNodeParameter('timestamps', itemIndex, false);
+        const stream = this.getNodeParameter('stream', itemIndex, 'both');
+        // Resolve name to ID first
+        const resolved = await (0, resolveContainer_1.resolveContainer)(docker, containerId);
+        const container = docker.getContainer(resolved.id);
+        const logOptions = {
+            stdout: stream === 'both' || stream === 'stdout',
+            stderr: stream === 'both' || stream === 'stderr',
+            tail: tail === 0 ? undefined : tail,
+            follow: false,
+            timestamps,
+        };
+        // Get logs as a Buffer (follow: false returns Buffer)
+        const logsBuffer = await container.logs(logOptions);
+        // Demultiplex the Docker log format
+        const allLogs = demuxDockerLogs(logsBuffer);
+        // Filter logs based on stream selection
+        let logs = allLogs;
+        if (stream === 'stdout') {
+            logs = allLogs.filter((log) => log.stream === 'stdout');
+        }
+        else if (stream === 'stderr') {
+            logs = allLogs.filter((log) => log.stream === 'stderr');
+        }
+        return {
+            containerId: resolved.id,
+            shortId: resolved.id.substring(0, 12),
+            containerName: resolved.name,
+            logs,
+            lineCount: logs.length,
+            stream,
+            retrievedAt: new Date().toISOString(),
+        };
+    }
+    catch (error) {
+        throw new Error((0, errorHandler_1.translateDockerError)(error));
+    }
+}

package/dist/nodes/Docker/actions/container/list.operation.d.ts

@@ -0,0 +1,3 @@
+import Docker from 'dockerode';
+import { IExecuteFunctions } from 'n8n-workflow';
+export declare function listContainers(this: IExecuteFunctions, docker: Docker, itemIndex: number): Promise<any[]>;

package/dist/nodes/Docker/actions/container/list.operation.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listContainers = listContainers;
+const errorHandler_1 = require("../../helpers/errorHandler");
+const normalizeContainer_1 = require("../../helpers/normalizeContainer");
+/**
+ * Maps user-friendly status values to Docker API values
+ */
+const statusMap = {
+    stopped: 'exited',
+};
+async function listContainers(docker, itemIndex) {
+    try {
+        const showAll = this.getNodeParameter('showAll', itemIndex, false);
+        const filters = this.getNodeParameter('filters', itemIndex, {});
+        const includeLabels = this.getNodeParameter('includeLabels', itemIndex, true);
+        const listOptions = {
+            all: showAll,
+            filters: {},
+        };
+        // Build filters - map user-friendly values to Docker API values
+        if (filters.status && filters.status !== '') {
+            const dockerStatus = statusMap[filters.status.toLowerCase()] || filters.status;
+            listOptions.filters = {
+                status: [dockerStatus],
+            };
+        }
+        const containers = await docker.listContainers(listOptions);
+        // Normalize and filter by name if provided
+        let normalized = containers.map((c) => (0, normalizeContainer_1.normalizeContainerInfo)(c, includeLabels));
+        if (filters.name && filters.name !== '') {
+            const nameFilter = filters.name.toLowerCase();
+            normalized = normalized.filter((c) => c.name.toLowerCase().includes(nameFilter));
+        }
+        return normalized;
+    }
+    catch (error) {
+        throw new Error((0, errorHandler_1.translateDockerError)(error));
+    }
+}

package/dist/nodes/Docker/actions/container/start.operation.d.ts

@@ -0,0 +1,3 @@
+import Docker from 'dockerode';
+import { IExecuteFunctions } from 'n8n-workflow';
+export declare function startContainer(this: IExecuteFunctions, docker: Docker, itemIndex: number): Promise<any>;