@better-openclaw/core 1.0.16 → 1.0.18

package/src/generators/cloud-init.ts

@@ -0,0 +1,137 @@
+/**
+ * Generates a cloud-init.yml file for deploying the stack to a VPS.
+ * Compatible with Hetzner, DigitalOcean, Vultr, Linode, and any provider
+ * that supports cloud-init user data.
+ *
+ * Based on the patterns from openclaw_docker-setup.sh and openclaw_install.sh:
+ * 1. Installs Docker via the official convenience script
+ * 2. Adds the default user to the docker group
+ * 3. Verifies Docker Compose v2 plugin is available
+ * 4. Creates /opt/openclaw/ with config, workspace, and identity directories
+ * 5. Writes docker-compose.yml and .env inline (env with restrictive 0600 perms)
+ * 6. Starts the stack with docker compose up -d
+ * 7. Polls the gateway health endpoint until it responds (up to 120s)
+ * 8. Logs all operations to /opt/openclaw/deploy.log
+ */
+export function generateCloudInit(options: {
+	composeYaml: string;
+	envContent: string;
+	projectName: string;
+	gatewayPort?: number;
+}): string {
+	const gatewayPort = options.gatewayPort ?? 18789;
+
+	// Escape content for cloud-init write_files (indent by 8 spaces)
+	const indentContent = (content: string) =>
+		content
+			.split("\n")
+			.map((line) => `        ${line}`)
+			.join("\n");
+
+	return `#cloud-config
+# Cloud-init for ${options.projectName}
+# Generated by better-openclaw
+# Compatible with: Hetzner, DigitalOcean, Vultr, Linode, AWS, GCP
+
+package_update: true
+
+packages:
+  - curl
+  - git
+  - ca-certificates
+  - gnupg
+
+write_files:
+  - path: /opt/openclaw/docker-compose.yml
+    permissions: "0644"
+    content: |
+${indentContent(options.composeYaml)}
+
+  - path: /opt/openclaw/.env
+    permissions: "0600"
+    content: |
+${indentContent(options.envContent)}
+
+  - path: /opt/openclaw/deploy.sh
+    permissions: "0755"
+    content: |
+        #!/usr/bin/env bash
+        # OpenClaw deployment script — runs as runcmd via cloud-init
+        # All output logged to /opt/openclaw/deploy.log
+        set -euo pipefail
+        exec > >(tee -a /opt/openclaw/deploy.log) 2>&1
+        echo "==> [$(date -u +%Y-%m-%dT%H:%M:%SZ)] Starting OpenClaw deployment"
+
+        # Install Docker via official convenience script
+        echo "==> Installing Docker"
+        curl -fsSL https://get.docker.com | sh
+
+        # Enable and start Docker daemon
+        systemctl enable docker
+        systemctl start docker
+
+        # Add default user to docker group (cloud providers commonly use 'ubuntu' or 'root')
+        DEFAULT_USER="\${SUDO_USER:-$(logname 2>/dev/null || echo root)}"
+        if [ "$DEFAULT_USER" != "root" ]; then
+          usermod -aG docker "$DEFAULT_USER"
+          echo "==> Added $DEFAULT_USER to docker group"
+        fi
+
+        # Verify Docker Compose v2 plugin
+        if ! docker compose version >/dev/null 2>&1; then
+          echo "ERROR: Docker Compose v2 plugin not available" >&2
+          exit 1
+        fi
+        echo "==> Docker Compose: $(docker compose version)"
+
+        # Create openclaw directories (matching docker-setup.sh structure)
+        # config: gateway config files (openclaw.json)
+        # workspace: agent workspace and data
+        # identity: device identity for Docker Desktop/Windows bind mount compat
+        mkdir -p /opt/openclaw/openclaw/config
+        mkdir -p /opt/openclaw/openclaw/workspace
+        mkdir -p /opt/openclaw/openclaw/config/identity
+
+        # Start the stack
+        echo "==> Starting stack"
+        cd /opt/openclaw
+        docker compose up -d
+
+        # Health check: poll gateway until it responds (up to 120 seconds)
+        echo "==> Waiting for gateway health check on port ${gatewayPort}"
+        RETRIES=60
+        while [ "$RETRIES" -gt 0 ]; do
+          if curl -sf "http://127.0.0.1:${gatewayPort}" >/dev/null 2>&1; then
+            echo "==> Gateway is healthy"
+            break
+          fi
+          RETRIES=$((RETRIES - 1))
+          sleep 2
+        done
+
+        if [ "$RETRIES" -eq 0 ]; then
+          echo "WARNING: Gateway did not respond within 120s. Check logs with:"
+          echo "  docker compose -f /opt/openclaw/docker-compose.yml logs -f openclaw-gateway"
+        fi
+
+        # Print summary
+        echo ""
+        echo "==> Deployment complete at $(date -u +%Y-%m-%dT%H:%M:%SZ)"
+        echo "    Project: ${options.projectName}"
+        echo "    Gateway: http://$(hostname -I | awk '{print $1}'):${gatewayPort}"
+        echo ""
+        echo "Useful commands:"
+        echo "  docker compose -f /opt/openclaw/docker-compose.yml logs -f"
+        echo "  docker compose -f /opt/openclaw/docker-compose.yml ps"
+        echo "  docker compose -f /opt/openclaw/docker-compose.yml restart"
+        echo ""
+        echo "Channel setup (optional):"
+        echo "  docker compose -f /opt/openclaw/docker-compose.yml run --rm openclaw-cli channels login"
+        echo "  docker compose -f /opt/openclaw/docker-compose.yml run --rm openclaw-cli channels add --channel telegram --token <TOKEN>"
+
+runcmd:
+  - /opt/openclaw/deploy.sh
+
+final_message: "OpenClaw stack '${options.projectName}' is ready! Connect to port ${gatewayPort}."
+`;
+}

package/src/generators/env.ts

@@ -11,6 +11,12 @@ export interface EnvGeneratorOptions {
 	openclawVersion?: string;
 	/** When set, host-like vars (e.g. REDIS_HOST) for these services use host.docker.internal so gateway in Docker can reach native services on host. */
 	nativeServiceIds?: Set<string>;
+	/** Compose file names for COMPOSE_FILE env var (enables `docker compose up` without -f flags). */
+	composeFiles?: string[];
+	/** Compose profiles for COMPOSE_PROFILES env var (enables `docker compose up` without --profile flags). */
+	composeProfiles?: string[];
+	/** OpenClaw image variant (official, coolify, alpine). */
+	openclawImage?: "official" | "coolify" | "alpine";
 }
 
 /**
@@ -26,6 +32,43 @@ export function generateEnvFiles(
 	const version = options.openclawVersion ?? "latest";
 	const lines: { comment: string; key: string; exampleValue: string; actualValue: string }[] = [];
 
+	// Track all env var values for resolving references later
+	const envVarValues = new Map<string, string>();
+
+	// ── Docker Compose convenience vars ─────────────────────────────────────
+	// These let you run `docker compose up -d` without -f and --profile flags.
+
+	if (options.composeFiles && options.composeFiles.length > 0) {
+		const separator = process.platform === "win32" ? ";" : ":";
+		const composeFileValue = options.composeFiles.join(separator);
+		lines.push({
+			comment: formatComment(
+				"Compose files to load (allows plain `docker compose up -d`)",
+				"Docker Compose",
+				false,
+				false,
+			),
+			key: "COMPOSE_FILE",
+			exampleValue: composeFileValue,
+			actualValue: composeFileValue,
+		});
+	}
+
+	if (options.composeProfiles && options.composeProfiles.length > 0) {
+		const profilesValue = options.composeProfiles.join(",");
+		lines.push({
+			comment: formatComment(
+				"Profiles to activate (allows plain `docker compose up -d`)",
+				"Docker Compose",
+				false,
+				false,
+			),
+			key: "COMPOSE_PROFILES",
+			exampleValue: profilesValue,
+			actualValue: profilesValue,
+		});
+	}
+
 	// ── Base OpenClaw Variables ──────────────────────────────────────────────
 
 	lines.push({
@@ -70,7 +113,7 @@ export function generateEnvFiles(
 
 	lines.push({
 		comment: formatComment(
-			"Gateway network bind mode (lan for Docker networking, loopback for local-only)",
+			"Gateway network bind mode: 'lan' (all interfaces, required for Docker). Use 'loopback' only for native (non-Docker) installs with Tailscale serve/funnel",
 			"OpenClaw Core",
 			false,
 			false,
@@ -104,15 +147,59 @@ export function generateEnvFiles(
 		actualValue: "./openclaw/workspace",
 	});
 
+	// Set OPENCLAW_IMAGE based on variant (empty = use compose default)
+	const imageVariantMap: Record<string, string> = {
+		official: "", // use compose default (ghcr.io/openclaw/openclaw:VERSION)
+		coolify: "coollabsio/openclaw:latest",
+		alpine: "alpine/openclaw:latest",
+	};
+	const imageValue = imageVariantMap[options.openclawImage ?? "official"] ?? "";
+
 	lines.push({
 		comment: formatComment(
-			"OpenClaw Docker image override (default uses ghcr.io/openclaw/openclaw)",
+			`OpenClaw Docker image variant: ${options.openclawImage ?? "official"} (official, coolify, alpine)`,
 			"OpenClaw Core",
 			false,
 			false,
 		),
 		key: "OPENCLAW_IMAGE",
 		exampleValue: "",
+		actualValue: imageValue,
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Extra bind mounts for gateway and CLI containers (comma-separated, format: source:target[:options])",
+			"OpenClaw Core",
+			false,
+			false,
+		),
+		key: "OPENCLAW_EXTRA_MOUNTS",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Named volume or host path for /home/node persistence across container restarts",
+			"OpenClaw Core",
+			false,
+			false,
+		),
+		key: "OPENCLAW_HOME_VOLUME",
+		exampleValue: "",
+		actualValue: "",
+	});
+
+	lines.push({
+		comment: formatComment(
+			"Extra apt packages to install during Docker image build (space-separated)",
+			"OpenClaw Core",
+			false,
+			false,
+		),
+		key: "OPENCLAW_DOCKER_APT_PACKAGES",
+		exampleValue: "",
 		actualValue: "",
 	});
 
@@ -137,13 +224,17 @@ export function generateEnvFiles(
 		});
 
 		for (const provider of resolved.aiProviders) {
+			// Local-only providers don't need API keys
 			if (provider === "ollama" || provider === "lmstudio" || provider === "vllm") continue;
 
-			const envKey = `${provider.toUpperCase()}_API_KEY`;
+			// Ollama Cloud uses OLLAMA_API_KEY (matches Ollama's official env var name)
+			const envKey =
+				provider === "ollama-cloud" ? "OLLAMA_API_KEY" : `${provider.toUpperCase()}_API_KEY`;
+			const label = provider === "ollama-cloud" ? "Ollama Cloud" : provider;
 			lines.push({
-				comment: formatComment(`API Key for ${provider} AI models`, "OpenClaw Core", true, true),
+				comment: formatComment(`API Key for ${label} AI models`, "OpenClaw Core", true, true),
 				key: envKey,
-				exampleValue: `your_${provider.toLowerCase()}_api_key_here`,
+				exampleValue: `your_${provider.toLowerCase().replace("-", "_")}_api_key_here`,
 				actualValue: "",
 			});
 		}
@@ -210,6 +301,9 @@ export function generateEnvFiles(
 		for (const req of dbReqs) {
 			const secretValue = options.generateSecrets ? randomBytes(24).toString("hex") : "";
 
+			// Store in map for later reference resolution
+			envVarValues.set(req.passwordEnvVar, secretValue);
+
 			lines.push({
 				comment: formatComment(
 					`PostgreSQL password for ${req.serviceName} (database: ${req.dbName}, user: ${req.dbUser})`,
@@ -237,6 +331,9 @@ export function generateEnvFiles(
 		"OPENCLAW_CONFIG_DIR",
 		"OPENCLAW_WORKSPACE_DIR",
 		"OPENCLAW_IMAGE",
+		"OPENCLAW_EXTRA_MOUNTS",
+		"OPENCLAW_HOME_VOLUME",
+		"OPENCLAW_DOCKER_APT_PACKAGES",
 		"OPENCLAW_DOMAIN",
 		"CLAUDE_AI_SESSION_KEY",
 		"CLAUDE_WEB_SESSION_KEY",
@@ -280,11 +377,20 @@ export function generateEnvFiles(
 			if (hostValue) {
 				actualValue = hostValue;
 			} else if (envVar.secret) {
-				actualValue = envVar.defaultValue.startsWith("${") ? envVar.defaultValue : secretValue;
+				// Resolve env var references like ${N8N_DB_PASSWORD}
+				if (envVar.defaultValue.startsWith("${") && envVar.defaultValue.endsWith("}")) {
+					const refKey = envVar.defaultValue.slice(2, -1); // Extract var name from ${VAR_NAME}
+					actualValue = envVarValues.get(refKey) || envVar.defaultValue;
+				} else {
+					actualValue = secretValue;
+				}
 			} else {
 				actualValue = envVar.defaultValue;
 			}
 
+			// Store in map for later reference resolution
+			envVarValues.set(envVar.key, actualValue);
+
 			lines.push({
 				comment: formatComment(envVar.description, definition.name, envVar.required, envVar.secret),
 				key: envVar.key,

package/src/generators/health-check.ts

@@ -2,9 +2,9 @@ import type { ResolverOutput } from "../types.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
-interface HealthCheckOptions {
+export interface HealthCheckOptions {
 	projectName: string;
-	deploymentType?: "docker" | "bare-metal";
+	deploymentType?: "docker" | "bare-metal" | "local";
 }
 
 // ─── Generator ──────────────────────────────────────────────────────────────

package/src/generators/openclaw-install-script.ts

@@ -0,0 +1,77 @@
+/**
+ * Generates the `scripts/install-openclaw.sh` and `scripts/install-openclaw.ps1`
+ * scripts that install OpenClaw directly on the host via the official installer.
+ */
+
+export interface OpenclawInstallScriptOptions {
+	projectName: string;
+}
+
+export function generateOpenclawInstallScript(
+	options: OpenclawInstallScriptOptions,
+): Record<string, string> {
+	const files: Record<string, string> = {};
+
+	// Bash script (macOS / Linux)
+	files["scripts/install-openclaw.sh"] = [
+		"#!/usr/bin/env bash",
+		"set -euo pipefail",
+		"",
+		`# Install OpenClaw directly on this host for project: ${options.projectName}`,
+		"# This script downloads and runs the official OpenClaw installer.",
+		"# It will install Node.js 22+ (if needed) and OpenClaw globally via npm.",
+		"",
+		'echo "╔══════════════════════════════════════════╗"',
+		'echo "║    OpenClaw — Direct Host Installation   ║"',
+		'echo "╚══════════════════════════════════════════╝"',
+		'echo ""',
+		"",
+		"# Run the official installer",
+		'curl -fsSL --proto "=https" --tlsv1.2 https://openclaw.ai/install.sh | bash',
+		"",
+		'echo ""',
+		'echo "OpenClaw installed successfully!"',
+		'echo ""',
+		'echo "Next steps:"',
+		'echo "  1. Start your companion services:  docker compose up -d"',
+		'echo "  2. Run onboarding:                  openclaw onboard"',
+		'echo "  3. Launch the dashboard:             openclaw dashboard"',
+		'echo ""',
+		"",
+	].join("\n");
+
+	// PowerShell script (Windows / WSL)
+	files["scripts/install-openclaw.ps1"] = [
+		"# Install OpenClaw directly on this host (Windows via WSL)",
+		`# Project: ${options.projectName}`,
+		"#",
+		"# This script sets up WSL if needed, then runs the official Linux installer inside it.",
+		"",
+		'Write-Host "OpenClaw - Direct Host Installation" -ForegroundColor Cyan',
+		'Write-Host ""',
+		"",
+		"# Check if WSL is available",
+		"$wslCheck = Get-Command wsl -ErrorAction SilentlyContinue",
+		"if (-not $wslCheck) {",
+		'    Write-Host "WSL is not installed. Installing WSL..." -ForegroundColor Yellow',
+		"    wsl --install",
+		'    Write-Host "Please restart your computer and re-run this script." -ForegroundColor Yellow',
+		"    exit 1",
+		"}",
+		"",
+		'Write-Host "Running OpenClaw installer inside WSL..." -ForegroundColor Green',
+		"wsl bash -c \"curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash\"",
+		"",
+		'Write-Host ""',
+		'Write-Host "OpenClaw installed successfully inside WSL!" -ForegroundColor Green',
+		'Write-Host ""',
+		'Write-Host "Next steps:"',
+		'Write-Host "  1. Start your companion services:  docker compose up -d"',
+		'Write-Host "  2. Run onboarding (in WSL):         openclaw onboard"',
+		'Write-Host "  3. Launch the dashboard:             openclaw dashboard"',
+		'Write-Host ""',
+		"",
+	].join("\n");
+
+	return files;
+}