feat(rag): Docker auto-setup for Qdrant and Postgres with cloud detection and health polling

jddunn · jddunn · commit 4927430892f7 · 2026-03-26T17:53:52.000-07:00
diff --git a/src/rag/setup/DockerDetector.ts b/src/rag/setup/DockerDetector.ts
@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Docker environment detection and container management.
+ * @module rag/setup/DockerDetector
+ *
+ * Utility class for detecting whether Docker is available, checking
+ * container state, starting/stopping containers, and pulling images.
+ * Used by QdrantSetup and PostgresSetup for auto-provisioning.
+ */
+
+import { execSync } from 'node:child_process';
+
+export class DockerDetector {
+  /**
+   * Check if Docker is installed and the daemon is running.
+   * Runs `docker info` with a 5-second timeout.
+   *
+   * @returns True if Docker is available and responsive.
+   */
+  static isDockerAvailable(): boolean {
+    try {
+      execSync('docker info', { stdio: 'pipe', timeout: 5000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Check the state of a named Docker container.
+   *
+   * @param name - Container name to inspect.
+   * @returns 'running' if active, 'stopped' if exists but not running,
+   *          'not_found' if the container doesn't exist.
+   */
+  static getContainerState(name: string): 'running' | 'stopped' | 'not_found' {
+    try {
+      const output = execSync(
+        `docker inspect --format='{{.State.Running}}' "${name}"`,
+        { stdio: 'pipe', timeout: 5000 },
+      ).toString().trim();
+      // docker inspect returns 'true' or 'false' for .State.Running
+      return output === 'true' ? 'running' : 'stopped';
+    } catch {
+      // Container doesn't exist or docker not available.
+      return 'not_found';
+    }
+  }
+
+  /**
+   * Start a stopped container by name.
+   *
+   * @param name - Container name to start.
+   * @throws If the container cannot be started.
+   */
+  static startContainer(name: string): void {
+    execSync(`docker start "${name}"`, { stdio: 'pipe', timeout: 15000 });
+  }
+
+  /**
+   * Pull a Docker image and run a new container.
+   *
+   * @param opts.name    - Container name.
+   * @param opts.image   - Docker image (e.g. 'qdrant/qdrant:latest').
+   * @param opts.ports   - Port mappings (e.g. ['6333:6333', '6334:6334']).
+   * @param opts.volumes - Volume mounts (e.g. ['data-vol:/data']).
+   * @param opts.env     - Environment variables (e.g. { POSTGRES_PASSWORD: 'pw' }).
+   */
+  static pullAndRun(opts: {
+    name: string;
+    image: string;
+    ports: string[];
+    volumes: string[];
+    env?: Record<string, string>;
+  }): void {
+    // Pull the image first (allows progress output via pipe).
+    execSync(`docker pull "${opts.image}"`, { stdio: 'pipe', timeout: 120000 });
+
+    // Build the docker run command.
+    const portFlags = opts.ports.map(p => `-p ${p}`).join(' ');
+    const volFlags = opts.volumes.map(v => `-v ${v}`).join(' ');
+    const envFlags = opts.env
+      ? Object.entries(opts.env).map(([k, v]) => `-e "${k}=${v}"`).join(' ')
+      : '';
+
+    const cmd = [
+      'docker run -d',
+      `--name "${opts.name}"`,
+      portFlags,
+      volFlags,
+      envFlags,
+      `"${opts.image}"`,
+    ].filter(Boolean).join(' ');
+
+    execSync(cmd, { stdio: 'pipe', timeout: 30000 });
+  }
+
+  /**
+   * Poll a health check URL until it returns 200 or timeout is reached.
+   * Checks every 500ms.
+   *
+   * @param url       - Health check endpoint (e.g. 'http://localhost:6333/healthz').
+   * @param timeoutMs - Maximum time to wait in milliseconds. @default 15000
+   * @returns True if the endpoint became healthy within the timeout.
+   */
+  static async waitForHealthy(url: string, timeoutMs = 15000): Promise<boolean> {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const res = await fetch(url);
+        if (res.ok) return true;
+      } catch {
+        // Not ready yet — keep polling.
+      }
+      await new Promise(r => setTimeout(r, 500));
+    }
+    return false;
+  }
+
+  /**
+   * Get the mapped host port for a container's internal port.
+   * Useful when the host port was dynamically assigned.
+   *
+   * @param name         - Container name.
+   * @param internalPort - The container-internal port to look up.
+   * @returns The host port number, or null if not found.
+   */
+  static getHostPort(name: string, internalPort: number): number | null {
+    try {
+      const output = execSync(
+        `docker port "${name}" ${internalPort}`,
+        { stdio: 'pipe', timeout: 5000 },
+      ).toString().trim();
+      // Output format: "0.0.0.0:6333" or ":::6333"
+      const parts = output.split(':');
+      const port = parseInt(parts[parts.length - 1], 10);
+      return isNaN(port) ? null : port;
+    } catch {
+      return null;
+    }
+  }
+}
diff --git a/src/rag/setup/PostgresSetup.ts b/src/rag/setup/PostgresSetup.ts
@@ -0,0 +1,142 @@
+/**
+ * @fileoverview Postgres + pgvector auto-setup via Docker detection.
+ * @module rag/setup/PostgresSetup
+ *
+ * Detection flow:
+ * 1. Check DATABASE_URL / explicit connection string → pg_isready
+ * 2. Check Docker → existing container → start if stopped
+ * 3. Pull postgres:16 → run new container → install pgvector extension
+ */
+
+import { DockerDetector } from './DockerDetector.js';
+import type { BackendStatus, SetupConfig } from './types.js';
+
+/** Default container name for Wunderland-managed Postgres. */
+const CONTAINER_NAME = 'wunderland-postgres';
+/** Default port. */
+const DEFAULT_PORT = 5432;
+/** Default Docker image. */
+const IMAGE = 'postgres';
+/** Default password for auto-provisioned instances. */
+const DEFAULT_PASSWORD = 'wunderland';
+/** Default database name. */
+const DEFAULT_DB = 'agent_memory';
+
+export class PostgresSetup {
+  /**
+   * Detect and optionally provision a Postgres + pgvector instance.
+   *
+   * @param config - Optional setup overrides (port, image tag, URL).
+   * @returns Backend status with connection string.
+   */
+  static async detect(config?: SetupConfig): Promise<BackendStatus> {
+    const port = config?.port ?? DEFAULT_PORT;
+
+    // ── Step 1: Check explicit connection string or env var ──
+    const connStr = config?.url ?? process.env.DATABASE_URL;
+    if (connStr) {
+      try {
+        const pg = await import('pg');
+        const client = new pg.default.Client({ connectionString: connStr });
+        await client.connect();
+        // Check if pgvector is installed.
+        try {
+          await client.query("SELECT extname FROM pg_extension WHERE extname = 'vector'");
+        } catch {
+          // pgvector not installed — try to install it.
+          await client.query('CREATE EXTENSION IF NOT EXISTS vector');
+        }
+        await client.end();
+
+        // Detect cloud providers from connection string.
+        const isCloud = /neon|supabase|rds\.amazonaws|aiven/i.test(connStr);
+        return { status: 'running', url: connStr, source: isCloud ? 'cloud' : 'manual' };
+      } catch (err) {
+        return {
+          status: 'error',
+          url: connStr,
+          error: `Cannot connect to Postgres: ${err instanceof Error ? err.message : String(err)}`,
+        };
+      }
+    }
+
+    // ── Step 2: Check Docker availability ──
+    if (!DockerDetector.isDockerAvailable()) {
+      return {
+        status: 'no_docker',
+        error: 'Docker not found. Install Docker to auto-provision Postgres: https://docker.com/get-docker',
+      };
+    }
+
+    // ── Step 3: Check existing container ──
+    const localConnStr = `postgresql://postgres:${DEFAULT_PASSWORD}@localhost:${port}/${DEFAULT_DB}`;
+    const state = DockerDetector.getContainerState(CONTAINER_NAME);
+
+    if (state === 'running') {
+      return {
+        status: 'running',
+        url: localConnStr,
+        containerName: CONTAINER_NAME,
+        source: 'docker-local',
+      };
+    }
+
+    if (state === 'stopped') {
+      DockerDetector.startContainer(CONTAINER_NAME);
+      // Postgres needs a few seconds to accept connections after start.
+      await new Promise(r => setTimeout(r, 3000));
+      return {
+        status: 'running',
+        url: localConnStr,
+        containerName: CONTAINER_NAME,
+        source: 'docker-local',
+      };
+    }
+
+    // ── Step 4: Pull and run new container ──
+    const tag = config?.imageTag ?? '16';
+    try {
+      DockerDetector.pullAndRun({
+        name: CONTAINER_NAME,
+        image: `${IMAGE}:${tag}`,
+        ports: [`${port}:5432`],
+        volumes: ['wunderland-pg-data:/var/lib/postgresql/data'],
+        env: {
+          POSTGRES_DB: DEFAULT_DB,
+          POSTGRES_PASSWORD: DEFAULT_PASSWORD,
+        },
+      });
+    } catch (err) {
+      return {
+        status: 'error',
+        error: `Failed to start Postgres container: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+
+    // Wait for Postgres to accept connections.
+    await new Promise(r => setTimeout(r, 5000));
+
+    // ── Step 5: Install pgvector extension ──
+    try {
+      const pg = await import('pg');
+      const client = new pg.default.Client({ connectionString: localConnStr });
+      await client.connect();
+      await client.query('CREATE EXTENSION IF NOT EXISTS vector');
+      await client.end();
+    } catch (err) {
+      return {
+        status: 'error',
+        url: localConnStr,
+        containerName: CONTAINER_NAME,
+        error: `Postgres running but pgvector install failed: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+
+    return {
+      status: 'running',
+      url: localConnStr,
+      containerName: CONTAINER_NAME,
+      source: 'docker-local',
+    };
+  }
+}
diff --git a/src/rag/setup/QdrantSetup.ts b/src/rag/setup/QdrantSetup.ts
@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Qdrant auto-setup via Docker detection and provisioning.
+ * @module rag/setup/QdrantSetup
+ *
+ * Detection flow:
+ * 1. Check QDRANT_URL / explicit URL → health check
+ * 2. Check Docker → existing container → start if stopped
+ * 3. Pull qdrant/qdrant image → run new container
+ * 4. Poll /healthz until ready
+ */
+
+import { DockerDetector } from './DockerDetector.js';
+import type { BackendStatus, SetupConfig } from './types.js';
+
+/** Default container name for Wunderland-managed Qdrant. */
+const CONTAINER_NAME = 'wunderland-qdrant';
+/** Default Qdrant REST API port. */
+const DEFAULT_PORT = 6333;
+/** Default Qdrant gRPC port. */
+const DEFAULT_GRPC_PORT = 6334;
+/** Default Docker image. */
+const IMAGE = 'qdrant/qdrant';
+
+export class QdrantSetup {
+  /**
+   * Detect and optionally provision a Qdrant instance.
+   *
+   * Priority order:
+   * 1. Explicit URL or QDRANT_URL env var → direct health check
+   * 2. Docker container named 'wunderland-qdrant' → start if stopped
+   * 3. Pull and run a new Docker container
+   *
+   * @param config - Optional setup overrides (port, image tag, URL, API key).
+   * @returns Backend status with URL and connection details.
+   */
+  static async detect(config?: SetupConfig): Promise<BackendStatus> {
+    const port = config?.port ?? DEFAULT_PORT;
+
+    // ── Step 1: Check explicit URL or env var ──
+    const url = config?.url ?? process.env.QDRANT_URL;
+    if (url) {
+      try {
+        const res = await fetch(`${url.replace(/\/+$/, '')}/healthz`);
+        if (res.ok) {
+          // Determine if this is a cloud instance based on URL.
+          const isCloud = url.includes('cloud.qdrant.io') || !!config?.apiKey;
+          return { status: 'running', url, source: isCloud ? 'cloud' : 'manual' };
+        }
+      } catch {
+        return { status: 'error', url, error: `Cannot reach Qdrant at ${url}` };
+      }
+    }
+
+    // ── Step 2: Check Docker availability ──
+    if (!DockerDetector.isDockerAvailable()) {
+      return {
+        status: 'no_docker',
+        error: 'Docker not found. Install Docker to auto-provision Qdrant: https://docker.com/get-docker',
+      };
+    }
+
+    // ── Step 3: Check existing container ──
+    const state = DockerDetector.getContainerState(CONTAINER_NAME);
+    const localUrl = `http://localhost:${port}`;
+
+    if (state === 'running') {
+      return {
+        status: 'running',
+        url: localUrl,
+        containerName: CONTAINER_NAME,
+        source: 'docker-local',
+      };
+    }
+
+    if (state === 'stopped') {
+      DockerDetector.startContainer(CONTAINER_NAME);
+      const healthy = await DockerDetector.waitForHealthy(`${localUrl}/healthz`);
+      return healthy
+        ? { status: 'running', url: localUrl, containerName: CONTAINER_NAME, source: 'docker-local' }
+        : { status: 'error', containerName: CONTAINER_NAME, error: 'Qdrant container started but health check timed out' };
+    }
+
+    // ── Step 4: Pull and run new container ──
+    const tag = config?.imageTag ?? 'latest';
+    try {
+      DockerDetector.pullAndRun({
+        name: CONTAINER_NAME,
+        image: `${IMAGE}:${tag}`,
+        ports: [`${port}:${DEFAULT_PORT}`, `${port + 1}:${DEFAULT_GRPC_PORT}`],
+        volumes: ['wunderland-qdrant-data:/qdrant/storage'],
+      });
+    } catch (err) {
+      return {
+        status: 'error',
+        error: `Failed to start Qdrant container: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+
+    const healthy = await DockerDetector.waitForHealthy(`${localUrl}/healthz`, 20000);
+    return healthy
+      ? { status: 'running', url: localUrl, containerName: CONTAINER_NAME, source: 'docker-local' }
+      : { status: 'error', containerName: CONTAINER_NAME, error: 'Qdrant container created but health check timed out' };
+  }
+}
diff --git a/src/rag/setup/types.ts b/src/rag/setup/types.ts
