@better-openclaw/core 1.0.16 → 1.0.18

package/src/deployers/coolify.ts

@@ -0,0 +1,241 @@
+/**
+ * Coolify PaaS deployer — deploys Docker Compose stacks via the Coolify v4 REST API.
+ *
+ * API docs: https://coolify.io/docs/api-reference/api/
+ * Auth: Authorization: Bearer <token>
+ * Base path: /api/v1
+ */
+
+import type { DeployInput, DeployResult, DeployStep, DeployTarget, PaasDeployer } from "./types.js";
+
+/** Shape returned by Coolify's project endpoints. */
+interface CoolifyProject {
+	uuid: string;
+	name: string;
+	environments?: { uuid: string; name: string }[];
+}
+
+/** Shape returned by Coolify's server listing. */
+interface CoolifyServer {
+	uuid: string;
+	name: string;
+	ip: string;
+}
+
+/** Shape returned when creating a Coolify service (compose stack). */
+interface CoolifyService {
+	uuid: string;
+}
+
+/** Shape returned by Coolify's deploy trigger endpoint. */
+interface CoolifyDeployment {
+	message: string;
+	resource_uuid: string;
+	deployment_uuid: string;
+}
+
+/** Build a full Coolify API URL (base + /api/v1 + path). */
+function apiUrl(target: DeployTarget, path: string): string {
+	const base = target.instanceUrl.replace(/\/+$/, "");
+	return `${base}/api/v1${path}`;
+}
+
+/**
+ * Typed fetch wrapper for the Coolify v4 API.
+ * Handles JSON serialisation, Bearer auth, and error extraction.
+ */
+async function coolifyFetch<T>(
+	target: DeployTarget,
+	path: string,
+	options: { method?: string; body?: unknown } = {},
+): Promise<T> {
+	const res = await fetch(apiUrl(target, path), {
+		method: options.method ?? "GET",
+		headers: {
+			"Content-Type": "application/json",
+			Authorization: `Bearer ${target.apiKey}`,
+		},
+		body: options.body ? JSON.stringify(options.body) : undefined,
+	});
+
+	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
+		}
+		throw new Error(`Coolify API ${res.status}: ${detail}`);
+	}
+
+	const text = await res.text();
+	if (!text) return undefined as T;
+	return JSON.parse(text) as T;
+}
+
+/**
+ * Parse .env content into key-value pairs for Coolify's bulk env API.
+ */
+function parseEnvContent(envContent: string): {
+	key: string;
+	value: string;
+	is_preview: boolean;
+	is_build_time: boolean;
+	is_literal: boolean;
+}[] {
+	const result: {
+		key: string;
+		value: string;
+		is_preview: boolean;
+		is_build_time: boolean;
+		is_literal: boolean;
+	}[] = [];
+
+	for (const line of envContent.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+
+		const eqIdx = trimmed.indexOf("=");
+		if (eqIdx <= 0) continue;
+
+		const key = trimmed.slice(0, eqIdx);
+		const value = trimmed.slice(eqIdx + 1);
+
+		result.push({
+			key,
+			value,
+			is_preview: false,
+			is_build_time: false,
+			is_literal: true,
+		});
+	}
+
+	return result;
+}
+
+/**
+ * Deploys Docker Compose stacks to a Coolify v4 instance.
+ *
+ * Deploy flow (5 steps):
+ *   1. Discover the first available server
+ *   2. Create a Coolify project
+ *   3. Create a compose service with the raw docker-compose YAML
+ *   4. Push .env variables via the bulk env API
+ *   5. Trigger the deployment
+ */
+export class CoolifyDeployer implements PaasDeployer {
+	readonly name = "Coolify";
+	readonly id = "coolify";
+
+	async testConnection(target: DeployTarget): Promise<{ ok: boolean; error?: string }> {
+		try {
+			await coolifyFetch<unknown>(target, "/version");
+			return { ok: true };
+		} catch (err) {
+			return { ok: false, error: err instanceof Error ? err.message : String(err) };
+		}
+	}
+
+	async deploy(input: DeployInput): Promise<DeployResult> {
+		const steps: DeployStep[] = [
+			{ step: "Discover server", status: "pending" },
+			{ step: "Create project", status: "pending" },
+			{ step: "Create compose service", status: "pending" },
+			{ step: "Set environment variables", status: "pending" },
+			{ step: "Trigger deployment", status: "pending" },
+		];
+
+		const result: DeployResult = { success: false, steps };
+
+		try {
+			// Step 1: Discover default server
+			steps[0].status = "running";
+			const servers = await coolifyFetch<CoolifyServer[]>(input.target, "/servers");
+			if (!servers || servers.length === 0) {
+				throw new Error("No servers found in Coolify instance");
+			}
+			const server = servers[0];
+			steps[0].status = "done";
+			steps[0].detail = `Server: ${server.name} (${server.ip})`;
+
+			// Step 2: Create project
+			steps[1].status = "running";
+			const project = await coolifyFetch<CoolifyProject>(input.target, "/projects", {
+				method: "POST",
+				body: {
+					name: input.projectName,
+					description: input.description ?? `OpenClaw stack: ${input.projectName}`,
+				},
+			});
+			result.projectId = project.uuid;
+			steps[1].status = "done";
+			steps[1].detail = `Project: ${project.uuid}`;
+
+			// Get the default environment
+			const projectDetail = await coolifyFetch<CoolifyProject>(
+				input.target,
+				`/projects/${project.uuid}`,
+			);
+			const envUuid = projectDetail.environments?.[0]?.uuid;
+			const envName = projectDetail.environments?.[0]?.name ?? "production";
+			if (!envUuid) {
+				throw new Error("No default environment found in project");
+			}
+
+			// Step 3: Create compose service with docker_compose_raw
+			steps[2].status = "running";
+			const service = await coolifyFetch<CoolifyService>(input.target, "/services", {
+				method: "POST",
+				body: {
+					project_uuid: project.uuid,
+					server_uuid: server.uuid,
+					environment_name: envName,
+					environment_uuid: envUuid,
+					docker_compose_raw: input.composeYaml,
+					name: input.projectName,
+					description: input.description ?? "Deployed via OpenClaw web builder",
+					instant_deploy: false,
+				},
+			});
+			result.composeId = service.uuid;
+			steps[2].status = "done";
+			steps[2].detail = `Service: ${service.uuid}`;
+
+			// Step 4: Set environment variables
+			steps[3].status = "running";
+			const envVars = parseEnvContent(input.envContent);
+			if (envVars.length > 0) {
+				await coolifyFetch(input.target, `/services/${service.uuid}/envs`, {
+					method: "PATCH",
+					body: envVars,
+				});
+			}
+			steps[3].status = "done";
+			steps[3].detail = `${envVars.length} variables set`;
+
+			// Step 5: Trigger deployment
+			steps[4].status = "running";
+			const deployments = await coolifyFetch<{ deployments: CoolifyDeployment[] }>(
+				input.target,
+				`/deploy?uuid=${service.uuid}&force=true`,
+			);
+			steps[4].status = "done";
+			steps[4].detail = deployments?.deployments?.[0]?.deployment_uuid ?? "Deployment triggered";
+
+			result.success = true;
+			const base = input.target.instanceUrl.replace(/\/+$/, "");
+			result.dashboardUrl = `${base}/project/${project.uuid}`;
+		} catch (err) {
+			const failedIdx = steps.findIndex((s) => s.status === "running");
+			if (failedIdx >= 0) {
+				steps[failedIdx].status = "error";
+				steps[failedIdx].detail = err instanceof Error ? err.message : String(err);
+			}
+			result.error = err instanceof Error ? err.message : String(err);
+		}
+
+		return result;
+	}
+}

package/src/deployers/dokploy.ts

@@ -0,0 +1,174 @@
+/**
+ * Dokploy PaaS deployer — deploys Docker Compose stacks via the Dokploy REST API.
+ *
+ * API docs: https://docs.dokploy.com/docs/api
+ * Auth: x-api-key header
+ * Endpoints use dot-notation (e.g. /api/project.create, /api/compose.deploy)
+ */
+
+import type { DeployInput, DeployResult, DeployStep, DeployTarget, PaasDeployer } from "./types.js";
+
+/** Shape returned by Dokploy's project endpoints. */
+interface DokployProject {
+	projectId: string;
+	name: string;
+	description: string;
+	environments?: { environmentId: string; name: string }[];
+}
+
+/** Shape returned by Dokploy's compose endpoints. */
+interface DokployCompose {
+	composeId: string;
+	name: string;
+	status?: string;
+}
+
+/** Build a full Dokploy API URL from a dot-notation endpoint (e.g. "project.create"). */
+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.
+ */
+async function dokployFetch<T>(
+	target: DeployTarget,
+	endpoint: string,
+	options: { method?: string; body?: unknown } = {},
+): Promise<T> {
+	const res = await fetch(apiUrl(target, endpoint), {
+		method: options.method ?? "GET",
+		headers: {
+			"Content-Type": "application/json",
+			"x-api-key": target.apiKey,
+		},
+		body: options.body ? JSON.stringify(options.body) : undefined,
+	});
+
+	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
+		}
+		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;
+}
+
+/**
+ * Deploys Docker Compose stacks to a Dokploy instance.
+ *
+ * Deploy flow (4 steps):
+ *   1. Create a Dokploy project
+ *   2. Create a compose stack inside the project's default environment
+ *   3. Push .env variables to the compose stack
+ *   4. Trigger the deployment
+ */
+export class DokployDeployer implements PaasDeployer {
+	readonly name = "Dokploy";
+	readonly id = "dokploy";
+
+	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) };
+		}
+	}
+
+	async deploy(input: DeployInput): Promise<DeployResult> {
+		const steps: DeployStep[] = [
+			{ step: "Create project", status: "pending" },
+			{ step: "Create compose stack", status: "pending" },
+			{ step: "Set environment variables", status: "pending" },
+			{ step: "Trigger deployment", status: "pending" },
+		];
+
+		const result: DeployResult = { success: false, steps };
+
+		try {
+			// Step 1: Create project
+			steps[0].status = "running";
+			const project = await dokployFetch<DokployProject>(input.target, "project.create", {
+				method: "POST",
+				body: {
+					name: input.projectName,
+					description: input.description ?? `OpenClaw stack: ${input.projectName}`,
+				},
+			});
+			result.projectId = project.projectId;
+			steps[0].status = "done";
+			steps[0].detail = `Project ID: ${project.projectId}`;
+
+			// Get the default environment ID
+			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
+			steps[1].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;
+			steps[1].status = "done";
+			steps[1].detail = `Compose ID: ${compose.composeId}`;
+
+			// Step 3: Set environment variables
+			steps[2].status = "running";
+			await dokployFetch(input.target, "compose.update", {
+				method: "POST",
+				body: {
+					composeId: compose.composeId,
+					env: input.envContent,
+				},
+			});
+			steps[2].status = "done";
+
+			// Step 4: Trigger deployment
+			steps[3].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",
+				},
+			});
+			steps[3].status = "done";
+
+			result.success = true;
+			const base = input.target.instanceUrl.replace(/\/+$/, "");
+			result.dashboardUrl = `${base}/dashboard/project/${project.projectId}`;
+		} catch (err) {
+			const failedIdx = steps.findIndex((s) => s.status === "running");
+			if (failedIdx >= 0) {
+				steps[failedIdx].status = "error";
+				steps[failedIdx].detail = err instanceof Error ? err.message : String(err);
+			}
+			result.error = err instanceof Error ? err.message : String(err);
+		}
+
+		return result;
+	}
+}

package/src/deployers/index.ts

@@ -0,0 +1,36 @@
+/**
+ * PaaS deployer registry — barrel export + lookup helpers.
+ *
+ * To add a new provider, implement `PaasDeployer` and register it in
+ * `deployerRegistry` below.
+ */
+
+export { CoolifyDeployer } from "./coolify.js";
+export { DokployDeployer } from "./dokploy.js";
+export type {
+	DeployInput,
+	DeployResult,
+	DeployStep,
+	DeployTarget,
+	PaasDeployer,
+} from "./types.js";
+
+import { CoolifyDeployer } from "./coolify.js";
+import { DokployDeployer } from "./dokploy.js";
+import type { PaasDeployer } from "./types.js";
+
+/** Registry of all available PaaS deployers. */
+export const deployerRegistry: Record<string, PaasDeployer> = {
+	dokploy: new DokployDeployer(),
+	coolify: new CoolifyDeployer(),
+};
+
+/** Get a deployer by ID, or undefined if not found. */
+export function getDeployer(id: string): PaasDeployer | undefined {
+	return deployerRegistry[id];
+}
+
+/** List all available deployer IDs. */
+export function getAvailableDeployers(): string[] {
+	return Object.keys(deployerRegistry);
+}

package/src/deployers/types.ts

@@ -0,0 +1,70 @@
+/**
+ * Common types for PaaS deployers (Dokploy, Coolify, etc.)
+ *
+ * This module defines the contract that all PaaS deployment providers must
+ * implement. The deployer system is designed to be extensible — adding a new
+ * provider only requires implementing the `PaasDeployer` interface and
+ * registering it in `deployers/index.ts`.
+ *
+ * Architecture:
+ *   Web UI / CLI  -->  API relay (/v1/deploy)  -->  PaaS instance (Dokploy/Coolify)
+ *
+ * The API server acts as a relay to avoid CORS issues when deploying from the
+ * browser. The CLI calls the deployer directly (no relay needed).
+ */
+
+/** Credentials and connection info for a PaaS target. */
+export interface DeployTarget {
+	/** Base URL of the PaaS instance (e.g. "https://dokploy.example.com") */
+	instanceUrl: string;
+	/** API key / bearer token */
+	apiKey: string;
+}
+
+/** Input for a deploy operation. */
+export interface DeployInput {
+	/** Target PaaS connection */
+	target: DeployTarget;
+	/** Project name to create or use */
+	projectName: string;
+	/** Raw docker-compose.yml content */
+	composeYaml: string;
+	/** Raw .env file content (key=value lines) */
+	envContent: string;
+	/** Optional description */
+	description?: string;
+}
+
+/** Step-level status for deploy progress. */
+export interface DeployStep {
+	step: string;
+	status: "pending" | "running" | "done" | "error";
+	detail?: string;
+}
+
+/** Result of a deploy operation. */
+export interface DeployResult {
+	success: boolean;
+	/** URL to the deployed project/compose in the PaaS dashboard */
+	dashboardUrl?: string;
+	/** PaaS-assigned project ID */
+	projectId?: string;
+	/** PaaS-assigned compose/service ID */
+	composeId?: string;
+	/** Step-by-step progress */
+	steps: DeployStep[];
+	/** Error message if failed */
+	error?: string;
+}
+
+/** Interface that all PaaS deployers implement. */
+export interface PaasDeployer {
+	/** Human-readable name */
+	readonly name: string;
+	/** Identifier (e.g. "dokploy", "coolify") */
+	readonly id: string;
+	/** Test connection to the PaaS instance */
+	testConnection(target: DeployTarget): Promise<{ ok: boolean; error?: string }>;
+	/** Deploy a compose stack */
+	deploy(input: DeployInput): Promise<DeployResult>;
+}

package/src/generate.ts

@@ -7,18 +7,21 @@ import { composeMultiFile } from "./composer.js";
 import { StackConfigError, ValidationError } from "./errors.js";
 import { generateBareMetalInstall } from "./generators/bare-metal-install.js";
 import { generateCaddyfile } from "./generators/caddy.js";
+import { generateCloudInit } from "./generators/cloud-init.js";
 import { generateEnvFiles } from "./generators/env.js";
 import { generateGsdScripts } from "./generators/get-shit-done.js";
 import { generateGrafanaConfig, generateGrafanaDashboard } from "./generators/grafana.js";
 import { generateHealthCheck } from "./generators/health-check.js";
 import { generateN8nWorkflows } from "./generators/n8n-workflows.js";
 import { generateNativeInstallScripts } from "./generators/native-services.js";
+import { generateOpenclawInstallScript } from "./generators/openclaw-install-script.js";
 import { generateOpenClawConfig } from "./generators/openclaw-json.js";
 import { generatePostgresInit } from "./generators/postgres-init.js";
 import { generatePrometheusConfig } from "./generators/prometheus.js";
 import { generateReadme } from "./generators/readme.js";
 import { generateScripts } from "./generators/scripts.js";
 import { generateSkillFiles } from "./generators/skills.js";
+import { generateStackManifest } from "./generators/stack-manifest.js";
 import { generateTraefikConfig } from "./generators/traefik.js";
 import { migrateConfig } from "./migrations.js";
 import { resolve } from "./resolver.js";
@@ -91,6 +94,9 @@ export function generate(rawInput: GenerationInput): GenerationResult {
 	const composeOptions = {
 		projectName: input.projectName,
 		proxy: input.proxy,
+		proxyHttpPort: input.proxyHttpPort,
+		proxyHttpsPort: input.proxyHttpsPort,
+		portOverrides: input.portOverrides,
 		domain: input.domain,
 		gpu: input.gpu,
 		platform: composePlatform,
@@ -98,6 +104,9 @@ export function generate(rawInput: GenerationInput): GenerationResult {
 		openclawVersion: input.openclawVersion,
 		bareMetalNativeHost: isBareMetal && nativeIds.size > 0,
 		traefikLabels: traefikOutput?.serviceLabels,
+		openclawImage: input.openclawImage ?? "official",
+		hardened: input.hardened ?? true,
+		openclawInstallMethod: input.openclawInstallMethod ?? "docker",
 	};
 	const composeResult = composeMultiFile(resolvedForCompose, composeOptions);
 
@@ -126,6 +135,9 @@ export function generate(rawInput: GenerationInput): GenerationResult {
 		domain: input.domain,
 		openclawVersion: input.openclawVersion,
 		nativeServiceIds: isBareMetal ? nativeIds : undefined,
+		composeFiles: Object.keys(composeResult.files),
+		composeProfiles: composeResult.profiles,
+		openclawImage: input.openclawImage,
 	});
 	files[".env.example"] = envFiles.envExample;
 	files[".env"] = envFiles.env;
@@ -139,6 +151,12 @@ export function generate(rawInput: GenerationInput): GenerationResult {
 		"docker-compose.override.yml",
 	].join("\n");
 
+	// Stack manifest (consumed by Mission Control)
+	const manifestFiles = generateStackManifest(resolved, input);
+	for (const [path, content] of Object.entries(manifestFiles)) {
+		files[path] = content;
+	}
+
 	// Skills
 	const skillFiles = generateSkillFiles(resolved);
 	for (const [path, content] of Object.entries(skillFiles)) {
@@ -146,7 +164,11 @@ export function generate(rawInput: GenerationInput): GenerationResult {
 	}
 
 	// OpenClaw Core Configuration
-	files["openclaw/config/openclaw.json"] = generateOpenClawConfig(resolved);
+	files["openclaw/config/openclaw.json"] = generateOpenClawConfig(resolved, {
+		deploymentType: input.deploymentType,
+		gatewayPort: 18789,
+		openclawVersion: input.openclawVersion,
+	});
 
 	// README
 	files["README.md"] = generateReadme(resolved, {
@@ -155,6 +177,7 @@ export function generate(rawInput: GenerationInput): GenerationResult {
 		proxy: input.proxy,
 		deploymentType: input.deploymentType,
 		hasNativeServices: isBareMetal && nativeServices.length > 0,
+		openclawInstallMethod: input.openclawInstallMethod,
 	});
 
 	// Scripts
@@ -254,6 +277,27 @@ export function generate(rawInput: GenerationInput): GenerationResult {
 		}
 	}
 
+	// OpenClaw direct install scripts (host-based, no Docker gateway)
+	if (input.openclawInstallMethod === "direct") {
+		const installScripts = generateOpenclawInstallScript({
+			projectName: input.projectName,
+		});
+		for (const [path, content] of Object.entries(installScripts)) {
+			files[path] = content;
+		}
+	}
+
+	// Cloud-init deploy target
+	if (input.deployTarget === "cloud-init") {
+		const mainCompose = composeResult.files["docker-compose.yml"] ?? "";
+		files["cloud-init.yml"] = generateCloudInit({
+			composeYaml: mainCompose,
+			envContent: envFiles.env,
+			projectName: input.projectName,
+			gatewayPort: 18789,
+		});
+	}
+
 	// 5. Calculate metadata
 	const skillCount = resolved.services.reduce((sum, s) => sum + s.definition.skills.length, 0);