@better-openclaw/core 1.0.20 → 1.0.22

package/src/deployers/dokploy.ts

@@ -6,21 +6,37 @@
  * Endpoints use dot-notation (e.g. /api/project.create, /api/compose.deploy)
  */
 
-import type { DeployInput, DeployResult, DeployStep, DeployTarget, PaasDeployer } from "./types.js";
+import { sanitizeComposeForPaas } from "./strip-host-ports.js";
+import type {
+	DeployInput,
+	DeployResult,
+	DeployStep,
+	DeployTarget,
+	DokployEnvironment,
+	PaasDeployer,
+	PaasServer,
+} from "./types.js";
 
-/** Shape returned by Dokploy's project endpoints. */
 interface DokployProject {
 	projectId: string;
 	name: string;
 	description: string;
-	environments?: { environmentId: string; name: string }[];
+	environments?: DokployEnvironment[];
 }
 
-/** Shape returned by Dokploy's compose endpoints. */
 interface DokployCompose {
 	composeId: string;
 	name: string;
 	status?: string;
+	compose?: string;
+}
+
+interface ProjectCreateResult {
+	project: DokployProject;
+	projectId: string;
+	name: string;
+	description: string;
+	environments?: { environmentId: string; name: string }[];
 }
 
 /** Build a full Dokploy API URL from a dot-notation endpoint (e.g. "project.create"). */
@@ -28,7 +44,6 @@ function apiUrl(target: DeployTarget, endpoint: string): string {
 	const base = target.instanceUrl.replace(/\/+$/, "");
 	return `${base}/api/${endpoint}`;
 }
-
 /**
  * Typed fetch wrapper for the Dokploy API.
  * Handles JSON serialisation, x-api-key auth, and error extraction.
@@ -50,20 +65,35 @@ async function dokployFetch<T>(
 	if (!res.ok) {
 		const text = await res.text().catch(() => "");
 		let detail = text;
+
 		try {
 			const json = JSON.parse(text);
 			detail = json.message || json.error || text;
-		} catch {
-			// use raw text
-		}
+		} catch {}
+
 		throw new Error(`Dokploy API ${res.status}: ${detail}`);
 	}
 
 	const text = await res.text();
 	if (!text) return undefined as T;
+
 	return JSON.parse(text) as T;
 }
 
+/**
+ * Simple hash for compose diff detection
+ */
+function hashString(str: string) {
+	let hash = 0;
+
+	for (let i = 0; i < str.length; i++) {
+		hash = (hash << 5) - hash + str.charCodeAt(i);
+		hash |= 0;
+	}
+
+	return hash;
+}
+
 /**
  * Deploys Docker Compose stacks to a Dokploy instance.
  *
@@ -73,6 +103,7 @@ async function dokployFetch<T>(
  *   3. Push .env variables to the compose stack
  *   4. Trigger the deployment
  */
+
 export class DokployDeployer implements PaasDeployer {
 	readonly name = "Dokploy";
 	readonly id = "dokploy";
@@ -80,94 +111,217 @@ export class DokployDeployer implements PaasDeployer {
 	async testConnection(target: DeployTarget): Promise<{ ok: boolean; error?: string }> {
 		try {
 			await dokployFetch<DokployProject[]>(target, "project.all");
+
 			return { ok: true };
 		} catch (err) {
-			return { ok: false, error: err instanceof Error ? err.message : String(err) };
+			return {
+				ok: false,
+				error: err instanceof Error ? err.message : String(err),
+			};
+		}
+	}
+
+	async listServers(target: DeployTarget): Promise<PaasServer[]> {
+		try {
+			const servers = await dokployFetch<{ serverId: string; name: string; ipAddress: string }[]>(
+				target,
+				"server.all",
+			);
+			return servers.map((s) => ({
+				id: s.serverId,
+				name: s.name,
+				ip: s.ipAddress,
+			}));
+		} catch {
+			// Return empty list if server API is not available
+			return [];
 		}
 	}
 
 	async deploy(input: DeployInput): Promise<DeployResult> {
-		const step1: DeployStep = { step: "Create project", status: "pending" };
-		const step2: DeployStep = { step: "Create compose stack", status: "pending" };
-		const step3: DeployStep = { step: "Set environment variables", status: "pending" };
-		const step4: DeployStep = { step: "Trigger deployment", status: "pending" };
-		const steps: DeployStep[] = [step1, step2, step3, step4];
+		const step1: DeployStep = {
+			step: "Find or create project",
+			status: "pending",
+		};
+		const step2: DeployStep = {
+			step: "Find default environment",
+			status: "pending",
+		};
+		const step3: DeployStep = {
+			step: "Find or create compose stack",
+			status: "pending",
+		};
+		const step4: DeployStep = {
+			step: "Update stack configuration",
+			status: "pending",
+		};
+		const step5: DeployStep = { step: "Deploy stack", status: "pending" };
+		const steps: DeployStep[] = [step1, step2, step3, step4, step5];
 
 		const result: DeployResult = { success: false, steps };
 
+		// Strip host port bindings — Dokploy routes via Traefik,
+		// so host ports are unnecessary and cause "port already allocated" errors.
+		const composeYaml = sanitizeComposeForPaas(input.composeYaml);
+
 		try {
-			// Step 1: Create project
+			/**
+			 * STEP 1
+			 * Find or create project
+			 */
+
 			step1.status = "running";
-			const project = await dokployFetch<DokployProject>(input.target, "project.create", {
-				method: "POST",
-				body: {
-					name: input.projectName,
-					description: input.description ?? `OpenClaw stack: ${input.projectName}`,
-				},
-			});
+
+			const projects = await dokployFetch<DokployProject[]>(input.target, "project.all");
+
+			let project = projects.find((p) => p.name === input.projectName);
+
+			if (!project) {
+				const created = await dokployFetch<ProjectCreateResult>(input.target, "project.create", {
+					method: "POST",
+					body: {
+						name: input.projectName,
+						description: input.description ?? `OpenClaw stack: ${input.projectName}`,
+					},
+				});
+
+				project = created.project;
+			}
+
 			result.projectId = project.projectId;
+
 			step1.status = "done";
 			step1.detail = `Project ID: ${project.projectId}`;
 
-			// Get the default environment ID
+			/**
+			 * STEP 2
+			 * Find default environment
+			 */
+
+			step2.status = "running";
+
 			const projectDetail = await dokployFetch<DokployProject>(
 				input.target,
 				`project.one?projectId=${project.projectId}`,
 			);
-			const envId = projectDetail.environments?.[0]?.environmentId;
-			if (!envId) {
-				throw new Error("No default environment found in project");
-			}
 
-			// Step 2: Create compose stack
-			step2.status = "running";
-			const compose = await dokployFetch<DokployCompose>(input.target, "compose.create", {
-				method: "POST",
-				body: {
-					name: input.projectName,
-					environmentId: envId,
-					composeFile: input.composeYaml,
-				},
-			});
-			result.composeId = compose.composeId;
+			const env = projectDetail.environments?.find((e) => e.isDefault);
+
+			if (!env) throw new Error("No default environment");
+
 			step2.status = "done";
-			step2.detail = `Compose ID: ${compose.composeId}`;
+			step2.detail = env.environmentId;
+
+			/**
+			 * STEP 3
+			 * Find or create compose stack
+			 */
 
-			// Step 3: Set environment variables
 			step3.status = "running";
-			await dokployFetch(input.target, "compose.update", {
+
+			let stack: DokployCompose | null = null;
+
+			stack = await dokployFetch<DokployCompose>(input.target, "compose.create", {
 				method: "POST",
 				body: {
-					composeId: compose.composeId,
-					env: input.envContent,
+					name: input.projectName,
+					description: input.description ?? `Stack ${input.projectName}`,
+					environmentId: env.environmentId,
+					composeType: "docker-compose",
+					composeFile: composeYaml,
+					...(input.serverId ? { serverId: input.serverId } : {}),
 				},
 			});
+
+			// Dokploy's compose.create schema does NOT accept sourceType;
+			// it defaults to "github". We must update it to "raw" so the
+			// deploy step writes the compose file from the stored YAML
+			// instead of attempting to clone from a Git provider.
+			if (stack?.composeId) {
+				await dokployFetch(input.target, "compose.update", {
+					method: "POST",
+					body: {
+						composeId: stack.composeId,
+						sourceType: "raw",
+					},
+				});
+			}
+
+			result.composeId = stack?.composeId;
 			step3.status = "done";
+			step3.detail = stack?.composeId;
+
+			/**
+			 * STEP 4
+			 * Update stack if compose changed
+			 */
 
-			// Step 4: Trigger deployment
 			step4.status = "running";
+
+			const existingStack = await dokployFetch<DokployCompose>(
+				input.target,
+				`compose.one?composeId=${stack?.composeId}`,
+			);
+
+			const newHash = hashString(composeYaml);
+			const oldHash = hashString(existingStack.compose ?? "");
+
+			if (newHash !== oldHash) {
+				await dokployFetch(input.target, "compose.update", {
+					method: "POST",
+					body: {
+						composeId: stack?.composeId,
+						composeFile: composeYaml,
+						env: input.envContent ?? "",
+					},
+				});
+
+				step4.detail = "Stack updated";
+			} else {
+				step4.detail = "No compose changes";
+			}
+
+			step4.status = "done";
+
+			/**
+			 * STEP 5
+			 * Deploy
+			 */
+
+			step5.status = "running";
+
 			await dokployFetch(input.target, "compose.deploy", {
 				method: "POST",
 				body: {
-					composeId: compose.composeId,
-					title: `Initial deploy: ${input.projectName}`,
-					description: input.description ?? "Deployed via OpenClaw web builder",
+					composeId: stack?.composeId,
+
+					title: `Deploy ${input.projectName}`,
+
+					description: "CI deployment",
 				},
 			});
-			step4.status = "done";
+
+			step5.status = "done";
 
 			result.success = true;
+
 			const base = input.target.instanceUrl.replace(/\/+$/, "");
-			result.dashboardUrl = `${base}/dashboard/project/${project.projectId}`;
+
+			result.dashboardUrl = `${base}/dashboard/project/${project.projectId}/environment/${env.environmentId}/services/compose/${stack?.composeId}?tab=deployments`;
+
+			return result;
 		} catch (err) {
-			const failedStep = steps.find((s) => s.status === "running");
-			if (failedStep) {
-				failedStep.status = "error";
-				failedStep.detail = err instanceof Error ? err.message : String(err);
+			const running = steps.find((s) => s.status === "running");
+
+			if (running) {
+				running.status = "error";
+
+				running.detail = err instanceof Error ? err.message : String(err);
 			}
+
 			result.error = err instanceof Error ? err.message : String(err);
-		}
 
-		return result;
+			return result;
+		}
 	}
 }

package/src/deployers/index.ts

@@ -13,6 +13,7 @@ export type {
 	DeployStep,
 	DeployTarget,
 	PaasDeployer,
+	PaasServer,
 } from "./types.js";
 
 import { CoolifyDeployer } from "./coolify.js";

package/src/deployers/strip-host-ports.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from "vitest";
+import { stripHostPorts } from "./strip-host-ports.js";
+
+describe("stripHostPorts", () => {
+	it("strips host port from short syntax (host:container)", () => {
+		const yaml = `
+services:
+  web:
+    image: nginx
+    ports:
+      - "8080:80"
+      - "443:443"
+`;
+		const result = stripHostPorts(yaml);
+		expect(result).toContain('"80"');
+		expect(result).toContain('"443"');
+		expect(result).not.toContain("8080");
+	});
+
+	it("strips host IP and port from extended short syntax", () => {
+		const yaml = `
+services:
+  web:
+    image: nginx
+    ports:
+      - "0.0.0.0:8080:80"
+`;
+		const result = stripHostPorts(yaml);
+		expect(result).toContain('"80"');
+		expect(result).not.toContain("8080");
+		expect(result).not.toContain("0.0.0.0");
+	});
+
+	it("preserves protocol suffix", () => {
+		const yaml = `
+services:
+  web:
+    image: nginx
+    ports:
+      - "8080:80/tcp"
+      - "5353:53/udp"
+`;
+		const result = stripHostPorts(yaml);
+		expect(result).toContain("80/tcp");
+		expect(result).toContain("53/udp");
+		expect(result).not.toContain("8080");
+		expect(result).not.toContain("5353");
+	});
+
+	it("keeps container-only ports unchanged", () => {
+		const yaml = `
+services:
+  web:
+    image: nginx
+    ports:
+      - "80"
+`;
+		const result = stripHostPorts(yaml);
+		expect(result).toContain('"80"');
+	});
+
+	it("handles multiple services", () => {
+		const yaml = `
+services:
+  web:
+    image: nginx
+    ports:
+      - "8080:80"
+  redis:
+    image: redis
+    ports:
+      - "6379:6379"
+  searxng:
+    image: searxng/searxng
+    ports:
+      - "8888:8080"
+`;
+		const result = stripHostPorts(yaml);
+		expect(result).toContain('"80"');
+		expect(result).toContain('"6379"');
+		expect(result).toContain('"8080"');
+		expect(result).not.toContain("8888");
+	});
+
+	it("returns original YAML if no services section", () => {
+		const yaml = `version: "3"`;
+		const result = stripHostPorts(yaml);
+		expect(result).toBe(yaml);
+	});
+
+	it("handles services with no ports", () => {
+		const yaml = `
+services:
+  web:
+    image: nginx
+`;
+		const result = stripHostPorts(yaml);
+		expect(result).toContain("nginx");
+	});
+});

package/src/deployers/strip-host-ports.ts

@@ -0,0 +1,187 @@
+/**
+ * Strips host port bindings from a Docker Compose YAML string.
+ *
+ * When deploying to a PaaS like Dokploy or Coolify, services don't need
+ * host port mappings because routing is handled by the platform's built-in
+ * reverse proxy (Traefik). Binding to host ports causes "port already
+ * allocated" errors when ports are in use by other services on the server.
+ *
+ * Transforms port mappings:
+ *   "8080:8080"        → "8080"        (container port only)
+ *   "0.0.0.0:8080:80"  → "80"          (container port only)
+ *   "8080:80/tcp"       → "80/tcp"      (preserves protocol)
+ *   { published: 8080, target: 80 }    → { target: 80 }
+ *
+ * The `expose` field is left untouched since it only defines internal ports.
+ */
+
+import { parse, stringify } from "yaml";
+
+interface ComposeService {
+	ports?: (string | PortObject)[];
+	volumes?: (string | Record<string, unknown>)[];
+	[key: string]: unknown;
+}
+
+interface PortObject {
+	target: number;
+	published?: number | string;
+	host_ip?: string;
+	protocol?: string;
+	[key: string]: unknown;
+}
+
+interface ComposeFile {
+	services?: Record<string, ComposeService>;
+	[key: string]: unknown;
+}
+
+/**
+ * Strips host port bindings from a Docker Compose YAML string,
+ * keeping only the container (target) ports.
+ *
+ * Returns the modified YAML string.
+ */
+export function stripHostPorts(composeYaml: string): string {
+	const doc = parse(composeYaml) as ComposeFile;
+
+	if (!doc?.services) return composeYaml;
+
+	for (const [, service] of Object.entries(doc.services)) {
+		if (!service.ports || !Array.isArray(service.ports)) continue;
+
+		service.ports = service.ports.map((port) => {
+			if (typeof port === "string") {
+				return stripStringPort(port);
+			}
+			if (typeof port === "object" && port !== null) {
+				return stripObjectPort(port);
+			}
+			return port;
+		});
+	}
+
+	return stringify(doc, { lineWidth: 200 });
+}
+
+/**
+ * Strips host portion from a string port mapping.
+ *
+ * "8080:80"          → "80"
+ * "0.0.0.0:8080:80"  → "80"
+ * "80"               → "80"  (no change)
+ * "80/tcp"           → "80/tcp"
+ * "8080:80/tcp"      → "80/tcp"
+ */
+function stripStringPort(port: string): string {
+	// Split off protocol if present (e.g. "/tcp", "/udp")
+	const protocolIdx = port.lastIndexOf("/");
+	let protocol = "";
+	let portSpec = port;
+
+	if (protocolIdx > 0) {
+		protocol = port.substring(protocolIdx); // includes the "/"
+		portSpec = port.substring(0, protocolIdx);
+	}
+
+	// Split by ":" — formats are:
+	//   "80"                → container only
+	//   "8080:80"           → host:container
+	//   "0.0.0.0:8080:80"  → ip:host:container
+	const parts = portSpec.split(":");
+
+	// Take the last part as the container port
+	const containerPort = parts[parts.length - 1];
+
+	return `${containerPort}${protocol}`;
+}
+
+/**
+ * Strips host/published from an object port mapping.
+ *
+ * { target: 80, published: 8080 }  → { target: 80 }
+ */
+function stripObjectPort(port: PortObject): PortObject {
+	const { published: _, host_ip: __, ...rest } = port;
+	return rest;
+}
+
+/**
+ * Strips local bind mounts (paths starting with `./`) from a Docker
+ * Compose YAML string.
+ *
+ * When deploying to a PaaS like Dokploy or Coolify as a raw compose
+ * stack, there is no cloned repository — so host-relative volume mounts
+ * like `./postgres/init-databases.sh:/docker-entrypoint-initdb.d/...`
+ * will fail because the file doesn't exist on the remote server.
+ *
+ * Named volumes (e.g. `redis-data:/data`) and absolute system paths
+ * (e.g. `/var/run/docker.sock`) are kept intact.
+ */
+export function stripLocalBindMounts(composeYaml: string): string {
+	const doc = parse(composeYaml) as ComposeFile;
+
+	if (!doc?.services) return composeYaml;
+
+	for (const [, service] of Object.entries(doc.services)) {
+		if (!service.volumes || !Array.isArray(service.volumes)) continue;
+
+		service.volumes = (service.volumes as (string | Record<string, unknown>)[]).filter((vol) => {
+			if (typeof vol === "string") {
+				// Bind mounts starting with "./" reference local files
+				return !vol.startsWith("./");
+			}
+			// Object-form: { type: "bind", source: "./..." }
+			if (typeof vol === "object" && vol !== null) {
+				const src = (vol as Record<string, unknown>).source;
+				return !(typeof src === "string" && src.startsWith("./"));
+			}
+			return true;
+		});
+
+		// Remove empty volumes array to keep YAML clean
+		if (service.volumes.length === 0) {
+			delete service.volumes;
+		}
+	}
+
+	return stringify(doc, { lineWidth: 200 });
+}
+
+/**
+ * Strips security hardening options (`cap_drop`, `cap_add`, `security_opt`)
+ * from all services in a Docker Compose YAML string.
+ *
+ * Many Docker images (PostgreSQL, Redis, MinIO, etc.) start as root and
+ * use `gosu`/`su-exec` to drop privileges to a non-root user.  This
+ * requires `SETUID`, `SETGID`, and other capabilities.  The hardened
+ * compose output adds `cap_drop: ALL` + `no-new-privileges`, which
+ * prevents this user switch and causes containers to crash with:
+ *   "failed switching to 'postgres': operation not permitted"
+ *
+ * PaaS platforms (Dokploy, Coolify) manage their own container security,
+ * so these options are unnecessary and should be removed.
+ */
+export function stripSecurityHardening(composeYaml: string): string {
+	const doc = parse(composeYaml) as ComposeFile;
+
+	if (!doc?.services) return composeYaml;
+
+	for (const [, service] of Object.entries(doc.services)) {
+		delete service.cap_drop;
+		delete service.cap_add;
+		delete service.security_opt;
+	}
+
+	return stringify(doc, { lineWidth: 200 });
+}
+
+/**
+ * Applies all PaaS-specific sanitisations to a Docker Compose YAML string:
+ * 1. Strips host port bindings (avoids "port already allocated" errors)
+ * 2. Strips local bind mounts (files don't exist on remote PaaS servers)
+ * 3. Strips security hardening (cap_drop/security_opt break user switching)
+ */
+export function sanitizeComposeForPaas(composeYaml: string): string {
+	return stripSecurityHardening(stripLocalBindMounts(stripHostPorts(composeYaml)));
+}