@geekmidas/cli 0.48.0 → 0.50.0

package/src/deploy/index.ts

@@ -1,5 +1,53 @@
+/**
+ * Deploy Module
+ *
+ * Handles deployment of GKM workspaces to various providers (Docker, Dokploy).
+ *
+ * ## Per-App Database Credentials
+ *
+ * When deploying to Dokploy with Postgres, this module creates per-app database
+ * users with isolated schemas. This follows the same pattern as local dev mode
+ * (docker/postgres/init.sh).
+ *
+ * ### How It Works
+ *
+ * 1. **Provisioning**: Creates Postgres service with master credentials
+ * 2. **User Creation**: For each backend app that needs DATABASE_URL:
+ *    - Generates a unique password (stored in deploy state)
+ *    - Creates a database user with that password
+ *    - Assigns schema permissions based on app name
+ * 3. **Schema Assignment**:
+ *    - `api` app: Uses `public` schema (shared tables)
+ *    - Other apps (e.g., `auth`): Get their own schema with `search_path` set
+ * 4. **Environment Injection**: Each app receives its own DATABASE_URL
+ *
+ * ### Security
+ *
+ * - External Postgres port is enabled only during user creation, then disabled
+ * - Each app can only access its own schema
+ * - Credentials are stored in `.gkm/deploy-{stage}.json` (gitignored)
+ * - Subsequent deploys reuse existing credentials from state
+ *
+ * ### Example Flow
+ *
+ * ```
+ * gkm deploy --stage production
+ *   ├─ Create Postgres (user: postgres, db: myproject)
+ *   ├─ Enable external port temporarily
+ *   ├─ Create user "api" → public schema
+ *   ├─ Create user "auth" → auth schema (search_path=auth)
+ *   ├─ Disable external port
+ *   ├─ Deploy "api" with DATABASE_URL=postgresql://api:xxx@postgres:5432/myproject
+ *   └─ Deploy "auth" with DATABASE_URL=postgresql://auth:yyy@postgres:5432/myproject
+ * ```
+ *
+ * @module deploy
+ */
+
+import { randomBytes } from 'node:crypto';
 import { stdin as input, stdout as output } from 'node:process';
 import * as readline from 'node:readline/promises';
+import { Client as PgClient } from 'pg';
 import {
 	getDokployCredentials,
 	getDokployRegistryId,
@@ -16,6 +64,11 @@ import {
 	isDeployTargetSupported,
 } from '../workspace/index.js';
 import type { NormalizedWorkspace } from '../workspace/types.js';
+import {
+	orchestrateDns,
+	resolveHostnameToIp,
+	verifyDnsRecords,
+} from './dns/index.js';
 import { deployDocker, resolveDockerConfig } from './docker';
 import { deployDokploy } from './dokploy';
 import {
@@ -25,29 +78,33 @@ import {
 	type DokployRedis,
 } from './dokploy-api';
 import {
+	generatePublicUrlBuildArgs,
+	getPublicUrlArgNames,
+	isMainFrontendApp,
+	resolveHost,
+} from './domain.js';
+import {
+	type EnvResolverContext,
+	formatMissingVarsError,
+	validateEnvVars,
+} from './env-resolver.js';
+import { updateConfig } from './init';
+import { generateSecretsReport, prepareSecretsForAllApps } from './secrets.js';
+import { sniffAllApps } from './sniffer.js';
+import {
+	type AppDbCredentials,
 	createEmptyState,
+	getAllAppCredentials,
 	getApplicationId,
 	getPostgresId,
 	getRedisId,
 	readStageState,
+	setAppCredentials,
 	setApplicationId,
 	setPostgresId,
 	setRedisId,
 	writeStageState,
 } from './state.js';
-import { orchestrateDns } from './dns/index.js';
-import {
-	generatePublicUrlBuildArgs,
-	getPublicUrlArgNames,
-	isMainFrontendApp,
-	resolveHost,
-} from './domain.js';
-import { updateConfig } from './init';
-import {
-	generateSecretsReport,
-	prepareSecretsForAllApps,
-} from './secrets.js';
-import { sniffAllApps } from './sniffer.js';
 import type {
 	AppDeployResult,
 	DeployOptions,
@@ -149,6 +206,211 @@ export interface ProvisionServicesResult {
 	};
 }
 
+/**
+ * Configuration for a database user to create during Dokploy deployment.
+ *
+ * @property name - The database username (typically matches the app name)
+ * @property password - The generated password for this user
+ * @property usePublicSchema - If true, user gets access to public schema (for api app).
+ *                             If false, user gets their own schema with search_path set.
+ */
+interface DbUserConfig {
+	name: string;
+	password: string;
+	usePublicSchema: boolean;
+}
+
+/**
+ * Wait for Postgres to be ready to accept connections.
+ *
+ * Polls the Postgres server until it accepts a connection or max retries reached.
+ * Used after enabling the external port to ensure the database is accessible
+ * before creating users.
+ *
+ * @param host - The Postgres server hostname
+ * @param port - The external port (typically 5432)
+ * @param user - Master database user (postgres)
+ * @param password - Master database password
+ * @param database - Database name to connect to
+ * @param maxRetries - Maximum number of connection attempts (default: 30)
+ * @param retryIntervalMs - Milliseconds between retries (default: 2000)
+ * @throws Error if Postgres is not ready after maxRetries
+ */
+async function waitForPostgres(
+	host: string,
+	port: number,
+	user: string,
+	password: string,
+	database: string,
+	maxRetries = 30,
+	retryIntervalMs = 2000,
+): Promise<void> {
+	for (let i = 0; i < maxRetries; i++) {
+		try {
+			const client = new PgClient({ host, port, user, password, database });
+			await client.connect();
+			await client.end();
+			return;
+		} catch {
+			if (i < maxRetries - 1) {
+				logger.log(`   Waiting for Postgres... (${i + 1}/${maxRetries})`);
+				await new Promise((r) => setTimeout(r, retryIntervalMs));
+			}
+		}
+	}
+	throw new Error(`Postgres not ready after ${maxRetries} retries`);
+}
+
+/**
+ * Initialize Postgres with per-app users and schemas.
+ *
+ * This function implements the same user/schema isolation pattern used in local
+ * dev mode (see docker/postgres/init.sh). It:
+ *
+ * 1. Temporarily enables the external Postgres port
+ * 2. Connects using master credentials
+ * 3. Creates each user with appropriate schema permissions
+ * 4. Disables the external port for security
+ *
+ * Schema assignment follows this pattern:
+ * - `api` app: Uses `public` schema (shared tables, migrations run here)
+ * - Other apps: Get their own schema with `search_path` configured
+ *
+ * @param api - The Dokploy API client
+ * @param postgres - The provisioned Postgres service details
+ * @param serverHostname - The Dokploy server hostname (for external connection)
+ * @param users - Array of users to create with their schema configuration
+ *
+ * @example
+ * ```ts
+ * await initializePostgresUsers(api, postgres, 'dokploy.example.com', [
+ *   { name: 'api', password: 'xxx', usePublicSchema: true },
+ *   { name: 'auth', password: 'yyy', usePublicSchema: false },
+ * ]);
+ * ```
+ */
+async function initializePostgresUsers(
+	api: DokployApi,
+	postgres: DokployPostgres,
+	serverHostname: string,
+	users: DbUserConfig[],
+): Promise<void> {
+	logger.log('\n🔧 Initializing database users...');
+
+	// Enable external port temporarily
+	const externalPort = 5432;
+	logger.log(`   Enabling external port ${externalPort}...`);
+	await api.savePostgresExternalPort(postgres.postgresId, externalPort);
+
+	// Redeploy to apply external port change
+	await api.deployPostgres(postgres.postgresId);
+
+	// Wait for Postgres to be ready with external port
+	logger.log(
+		`   Waiting for Postgres to be accessible at ${serverHostname}:${externalPort}...`,
+	);
+	await waitForPostgres(
+		serverHostname,
+		externalPort,
+		postgres.databaseUser,
+		postgres.databasePassword,
+		postgres.databaseName,
+	);
+
+	// Connect and create users
+	const client = new PgClient({
+		host: serverHostname,
+		port: externalPort,
+		user: postgres.databaseUser,
+		password: postgres.databasePassword,
+		database: postgres.databaseName,
+	});
+
+	try {
+		await client.connect();
+
+		for (const user of users) {
+			const schemaName = user.usePublicSchema ? 'public' : user.name;
+			logger.log(
+				`   Creating user "${user.name}" with schema "${schemaName}"...`,
+			);
+
+			// Create or update user (handles existing users)
+			await client.query(`
+				DO $$ BEGIN
+					CREATE USER "${user.name}" WITH PASSWORD '${user.password}';
+				EXCEPTION WHEN duplicate_object THEN
+					ALTER USER "${user.name}" WITH PASSWORD '${user.password}';
+				END $$;
+			`);
+
+			if (user.usePublicSchema) {
+				// API uses public schema
+				await client.query(`
+					GRANT ALL ON SCHEMA public TO "${user.name}";
+					ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO "${user.name}";
+					ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO "${user.name}";
+				`);
+			} else {
+				// Other apps get their own schema
+				await client.query(`
+					CREATE SCHEMA IF NOT EXISTS "${schemaName}" AUTHORIZATION "${user.name}";
+					ALTER USER "${user.name}" SET search_path TO "${schemaName}";
+					GRANT USAGE ON SCHEMA "${schemaName}" TO "${user.name}";
+					GRANT ALL ON ALL TABLES IN SCHEMA "${schemaName}" TO "${user.name}";
+					ALTER DEFAULT PRIVILEGES IN SCHEMA "${schemaName}" GRANT ALL ON TABLES TO "${user.name}";
+				`);
+			}
+
+			logger.log(`   ✓ User "${user.name}" configured`);
+		}
+	} finally {
+		await client.end();
+	}
+
+	// Disable external port for security
+	logger.log('   Disabling external port...');
+	await api.savePostgresExternalPort(postgres.postgresId, null);
+	await api.deployPostgres(postgres.postgresId);
+
+	logger.log('   ✓ Database users initialized');
+}
+
+/**
+ * Get the server hostname from the Dokploy endpoint URL
+ */
+function getServerHostname(endpoint: string): string {
+	const url = new URL(endpoint);
+	return url.hostname;
+}
+
+/**
+ * Build per-app DATABASE_URL for internal Docker network communication.
+ *
+ * The URL uses the Postgres container name (postgresAppName) as the host,
+ * which resolves via Docker's internal DNS when apps are in the same network.
+ *
+ * @param appName - The database username (matches the app name)
+ * @param appPassword - The app's database password
+ * @param postgresAppName - The Postgres container/service name in Dokploy
+ * @param databaseName - The database name (typically the project name)
+ * @returns A properly encoded PostgreSQL connection URL
+ *
+ * @example
+ * ```ts
+ * const url = buildPerAppDatabaseUrl('api', 'secret123', 'postgres-abc', 'myproject');
+ * // Returns: postgresql://api:secret123@postgres-abc:5432/myproject
+ * ```
+ */
+function buildPerAppDatabaseUrl(
+	appName: string,
+	appPassword: string,
+	postgresAppName: string,
+	databaseName: string,
+): string {
+	return `postgresql://${appName}:${encodeURIComponent(appPassword)}@${postgresAppName}:5432/${databaseName}`;
+}
+
 /**
  * Provision docker compose services in Dokploy
  * @internal Exported for testing
@@ -157,7 +419,7 @@ export async function provisionServices(
 	api: DokployApi,
 	projectId: string,
 	environmentId: string | undefined,
-	appName: string,
+	projectName: string,
 	services?: DockerComposeServices,
 	existingServiceIds?: { postgresId?: string; redisId?: string },
 ): Promise<ProvisionServicesResult | undefined> {
@@ -193,14 +455,15 @@ export async function provisionServices(
 
 			// If not found by ID, use findOrCreate
 			if (!postgres) {
-				const { randomBytes } = await import('node:crypto');
 				const databasePassword = randomBytes(16).toString('hex');
+				// Use project name as database name (replace hyphens with underscores for PostgreSQL)
+				const databaseName = projectName.replace(/-/g, '_');
 
 				const result = await api.findOrCreatePostgres(
 					postgresName,
 					projectId,
 					environmentId,
-					{ databasePassword },
+					{ databaseName, databasePassword },
 				);
 				postgres = result.postgres;
 				created = result.created;
@@ -230,8 +493,7 @@ export async function provisionServices(
 			serviceUrls.DATABASE_URL = `postgresql://${postgres.databaseUser}:${postgres.databasePassword}@${postgres.appName}:5432/${postgres.databaseName}`;
 			logger.log(`   ✓ Database credentials configured`);
 		} catch (error) {
-			const message =
-				error instanceof Error ? error.message : 'Unknown error';
+			const message = error instanceof Error ? error.message : 'Unknown error';
 			logger.log(`   ⚠ Failed to provision PostgreSQL: ${message}`);
 		}
 	}
@@ -297,8 +559,7 @@ export async function provisionServices(
 			serviceUrls.REDIS_URL = `redis://${password}${redis.appName}:6379`;
 			logger.log(`   ✓ Redis credentials configured`);
 		} catch (error) {
-			const message =
-				error instanceof Error ? error.message : 'Unknown error';
+			const message = error instanceof Error ? error.message : 'Unknown error';
 			logger.log(`   ⚠ Failed to provision Redis: ${message}`);
 		}
 	}
@@ -319,14 +580,6 @@ async function ensureDokploySetup(
 ): Promise<DokploySetupResult> {
 	logger.log('\n🔧 Checking Dokploy setup...');
 
-	// Read existing secrets to check if services are already configured
-	const { readStageSecrets } = await import('../secrets/storage');
-	const existingSecrets = await readStageSecrets(stage);
-	const existingUrls: { DATABASE_URL?: string; REDIS_URL?: string } = {
-		DATABASE_URL: existingSecrets?.urls?.DATABASE_URL,
-		REDIS_URL: existingSecrets?.urls?.REDIS_URL,
-	};
-
 	// Step 1: Ensure we have Dokploy credentials
 	let creds = await getDokployCredentials();
 
@@ -714,7 +967,9 @@ export async function workspaceDeployCommand(
 	const stageSecrets = await readStageSecrets(stage, workspace.root);
 	if (!stageSecrets) {
 		logger.log(`   ⚠️  No secrets found for stage "${stage}"`);
-		logger.log(`      Run "gkm secrets:init --stage ${stage}" to create secrets`);
+		logger.log(
+			`      Run "gkm secrets:init --stage ${stage}" to create secrets`,
+		);
 	}
 
 	// Sniff environment variables for all apps
@@ -729,7 +984,9 @@ export async function workspaceDeployCommand(
 	if (stageSecrets) {
 		const report = generateSecretsReport(encryptedSecrets, sniffedApps);
 		if (report.appsWithSecrets.length > 0) {
-			logger.log(`   ✓ Encrypted secrets for: ${report.appsWithSecrets.join(', ')}`);
+			logger.log(
+				`   ✓ Encrypted secrets for: ${report.appsWithSecrets.join(', ')}`,
+			);
 		}
 		if (report.appsWithMissingSecrets.length > 0) {
 			for (const { appName, missing } of report.appsWithMissingSecrets) {
@@ -883,6 +1140,10 @@ export async function workspaceDeployCommand(
 		redis: services.cache !== undefined && services.cache !== false,
 	};
 
+	// Track provisioned postgres info for per-app DATABASE_URL
+	let provisionedPostgres: DokployPostgres | null = null;
+	let provisionedRedis: DokployRedis | null = null;
+
 	if (dockerServices.postgres || dockerServices.redis) {
 		logger.log('\n🔧 Provisioning infrastructure services...');
 		// Pass existing service IDs from state (prefer state over URL sniffing)
@@ -904,9 +1165,17 @@ export async function workspaceDeployCommand(
 		if (provisionResult?.serviceIds) {
 			if (provisionResult.serviceIds.postgresId) {
 				setPostgresId(state, provisionResult.serviceIds.postgresId);
+				// Fetch full postgres info for later use
+				provisionedPostgres = await api.getPostgres(
+					provisionResult.serviceIds.postgresId,
+				);
 			}
 			if (provisionResult.serviceIds.redisId) {
 				setRedisId(state, provisionResult.serviceIds.redisId);
+				// Fetch full redis info for later use
+				provisionedRedis = await api.getRedis(
+					provisionResult.serviceIds.redisId,
+				);
 			}
 		}
 	}
@@ -921,6 +1190,60 @@ export async function workspaceDeployCommand(
 		(name) => workspace.apps[name]!.type === 'frontend',
 	);
 
+	// ==================================================================
+	// Initialize per-app database users if Postgres is provisioned
+	// ==================================================================
+	const perAppDbCredentials = new Map<string, AppDbCredentials>();
+
+	if (provisionedPostgres && backendApps.length > 0) {
+		// Determine which backend apps need DATABASE_URL
+		const appsNeedingDb = backendApps.filter((appName) => {
+			const requirements = sniffedApps.get(appName);
+			return requirements?.requiredEnvVars.includes('DATABASE_URL');
+		});
+
+		if (appsNeedingDb.length > 0) {
+			logger.log(`\n🔐 Setting up per-app database credentials...`);
+			logger.log(`   Apps needing DATABASE_URL: ${appsNeedingDb.join(', ')}`);
+
+			// Get or generate credentials for each app
+			const existingCredentials = getAllAppCredentials(state);
+			const usersToCreate: DbUserConfig[] = [];
+
+			for (const appName of appsNeedingDb) {
+				let credentials = existingCredentials[appName];
+
+				if (credentials) {
+					logger.log(`   ${appName}: Using existing credentials from state`);
+				} else {
+					// Generate new credentials
+					const password = randomBytes(16).toString('hex');
+					credentials = { dbUser: appName, dbPassword: password };
+					setAppCredentials(state, appName, credentials);
+					logger.log(`   ${appName}: Generated new credentials`);
+				}
+
+				perAppDbCredentials.set(appName, credentials);
+
+				// Always add to users to create (idempotent - will update if exists)
+				usersToCreate.push({
+					name: appName,
+					password: credentials.dbPassword,
+					usePublicSchema: appName === 'api', // API uses public schema, others get their own
+				});
+			}
+
+			// Initialize database users
+			const serverHostname = getServerHostname(creds.endpoint);
+			await initializePostgresUsers(
+				api,
+				provisionedPostgres,
+				serverHostname,
+				usersToCreate,
+			);
+		}
+	}
+
 	// Track deployed app public URLs for frontend builds
 	const publicUrls: Record<string, string> = {};
 	const results: AppDeployResult[] = [];
@@ -930,6 +1253,23 @@ export async function workspaceDeployCommand(
 	const appHostnames = new Map<string, string>(); // appName -> hostname
 	const appDomainIds = new Map<string, string>(); // appName -> domainId
 
+	// ==================================================================
+	// PRE-COMPUTE: Frontend URLs for BETTER_AUTH_TRUSTED_ORIGINS
+	// ==================================================================
+	const frontendUrls: string[] = [];
+	for (const appName of frontendApps) {
+		const app = workspace.apps[appName]!;
+		const isMainFrontend = isMainFrontendApp(appName, app, workspace.apps);
+		const hostname = resolveHost(
+			appName,
+			app,
+			stage,
+			dokployConfig,
+			isMainFrontend,
+		);
+		frontendUrls.push(`https://${hostname}`);
+	}
+
 	// ==================================================================
 	// PHASE 1: Deploy backend apps (with encrypted secrets)
 	// ==================================================================
@@ -953,7 +1293,9 @@ export async function workspaceDeployCommand(
 					logger.log(`      Using cached ID: ${cachedAppId}`);
 					application = await api.getApplication(cachedAppId);
 					if (application) {
-						logger.log(`      ✓ Application found: ${application.applicationId}`);
+						logger.log(
+							`      ✓ Application found: ${application.applicationId}`,
+						);
 					} else {
 						logger.log(`      ⚠ Cached ID invalid, will create new`);
 					}
@@ -969,9 +1311,13 @@ export async function workspaceDeployCommand(
 					application = result.application;
 
 					if (result.created) {
-						logger.log(`      Created application: ${application.applicationId}`);
+						logger.log(
+							`      Created application: ${application.applicationId}`,
+						);
 					} else {
-						logger.log(`      Found existing application: ${application.applicationId}`);
+						logger.log(
+							`      Found existing application: ${application.applicationId}`,
+						);
 					}
 				}
 
@@ -1010,12 +1356,63 @@ export async function workspaceDeployCommand(
 					buildArgs,
 				});
 
-				// Prepare environment variables - ONLY inject GKM_MASTER_KEY
-				const envVars: string[] = [`NODE_ENV=production`, `PORT=${app.port}`];
+				// Compute hostname first (needed for BETTER_AUTH_URL)
+				const backendHost = resolveHost(
+					appName,
+					app,
+					stage,
+					dokployConfig,
+					false, // Backend apps are not main frontend
+				);
+
+				// Build env resolver context
+				const envContext: EnvResolverContext = {
+					app,
+					appName,
+					stage,
+					state,
+					appCredentials: perAppDbCredentials.get(appName),
+					postgres: provisionedPostgres
+						? {
+								host: provisionedPostgres.appName,
+								port: 5432,
+								database: provisionedPostgres.databaseName,
+							}
+						: undefined,
+					redis: provisionedRedis
+						? {
+								host: provisionedRedis.appName,
+								port: 6379,
+								password: provisionedRedis.databasePassword,
+							}
+						: undefined,
+					appHostname: backendHost,
+					frontendUrls,
+					userSecrets: stageSecrets ?? undefined,
+					masterKey: appSecrets?.masterKey,
+				};
+
+				// Resolve all required environment variables
+				const appRequirements = sniffedApps.get(appName);
+				const requiredVars = appRequirements?.requiredEnvVars ?? [];
+				const { valid, missing, resolved } = validateEnvVars(
+					requiredVars,
+					envContext,
+				);
 
-				// Add master key for runtime decryption (NOT plain secrets)
-				if (appSecrets && appSecrets.masterKey) {
-					envVars.push(`GKM_MASTER_KEY=${appSecrets.masterKey}`);
+				if (!valid) {
+					throw new Error(formatMissingVarsError(appName, missing, stage));
+				}
+
+				// Build env vars string for Dokploy
+				const envVars: string[] = Object.entries(resolved).map(
+					([key, value]) => `${key}=${value}`,
+				);
+
+				if (Object.keys(resolved).length > 0) {
+					logger.log(
+						`      Resolved ${Object.keys(resolved).length} env vars: ${Object.keys(resolved).join(', ')}`,
+					);
 				}
 
 				// Configure and deploy application in Dokploy
@@ -1031,52 +1428,44 @@ export async function workspaceDeployCommand(
 				logger.log(`      Deploying to Dokploy...`);
 				await api.deployApplication(application.applicationId);
 
-				// Create domain for this app
-				const backendHost = resolveHost(
-					appName,
-					app,
-					stage,
-					dokployConfig,
-					false, // Backend apps are not main frontend
+				// Check if domain already exists (backendHost computed above)
+				const existingDomains = await api.getDomainsByApplicationId(
+					application.applicationId,
+				);
+				const existingDomain = existingDomains.find(
+					(d) => d.host === backendHost,
 				);
 
-				try {
-					const domain = await api.createDomain({
-						host: backendHost,
-						port: app.port,
-						https: true,
-						certificateType: 'letsencrypt',
-						applicationId: application.applicationId,
-					});
-
-					// Track for DNS orchestration
-					appHostnames.set(appName, backendHost);
-					appDomainIds.set(appName, domain.domainId);
-
-					const publicUrl = `https://${backendHost}`;
-					publicUrls[appName] = publicUrl;
-					logger.log(`      ✓ Domain: ${publicUrl}`);
-				} catch (domainError) {
-					// Domain might already exist, try to get the existing domain
+				if (existingDomain) {
+					// Domain already exists
 					appHostnames.set(appName, backendHost);
-
-					// Try to get existing domain ID for validation
+					appDomainIds.set(appName, existingDomain.domainId);
+					publicUrls[appName] = `https://${backendHost}`;
+					logger.log(`      ✓ Domain: https://${backendHost} (existing)`);
+				} else {
+					// Create new domain
 					try {
-						const existingDomains = await api.getDomainsByApplicationId(
-							application.applicationId,
-						);
-						const matchingDomain = existingDomains.find(
-							(d) => d.host === backendHost,
-						);
-						if (matchingDomain) {
-							appDomainIds.set(appName, matchingDomain.domainId);
-						}
-					} catch {
-						// Ignore - we'll just skip validation for this domain
+						const domain = await api.createDomain({
+							host: backendHost,
+							port: app.port,
+							https: true,
+							certificateType: 'letsencrypt',
+							applicationId: application.applicationId,
+						});
+
+						appHostnames.set(appName, backendHost);
+						appDomainIds.set(appName, domain.domainId);
+						publicUrls[appName] = `https://${backendHost}`;
+						logger.log(`      ✓ Domain: https://${backendHost} (created)`);
+					} catch (domainError) {
+						const message =
+							domainError instanceof Error
+								? domainError.message
+								: 'Unknown error';
+						logger.log(`      ⚠ Domain creation failed: ${message}`);
+						appHostnames.set(appName, backendHost);
+						publicUrls[appName] = `https://${backendHost}`;
 					}
-
-					publicUrls[appName] = `https://${backendHost}`;
-					logger.log(`      ℹ Domain already configured: https://${backendHost}`);
 				}
 
 				results.push({
@@ -1089,7 +1478,8 @@ export async function workspaceDeployCommand(
 
 				logger.log(`      ✓ ${appName} deployed successfully`);
 			} catch (error) {
-				const message = error instanceof Error ? error.message : 'Unknown error';
+				const message =
+					error instanceof Error ? error.message : 'Unknown error';
 				logger.log(`      ✗ Failed to deploy ${appName}: ${message}`);
 
 				results.push({
@@ -1130,7 +1520,9 @@ export async function workspaceDeployCommand(
 					logger.log(`      Using cached ID: ${cachedAppId}`);
 					application = await api.getApplication(cachedAppId);
 					if (application) {
-						logger.log(`      ✓ Application found: ${application.applicationId}`);
+						logger.log(
+							`      ✓ Application found: ${application.applicationId}`,
+						);
 					} else {
 						logger.log(`      ⚠ Cached ID invalid, will create new`);
 					}
@@ -1146,9 +1538,13 @@ export async function workspaceDeployCommand(
 					application = result.application;
 
 					if (result.created) {
-						logger.log(`      Created application: ${application.applicationId}`);
+						logger.log(
+							`      Created application: ${application.applicationId}`,
+						);
 					} else {
-						logger.log(`      Found existing application: ${application.applicationId}`);
+						logger.log(
+							`      Found existing application: ${application.applicationId}`,
+						);
 					}
 				}
 
@@ -1199,7 +1595,7 @@ export async function workspaceDeployCommand(
 				logger.log(`      Deploying to Dokploy...`);
 				await api.deployApplication(application.applicationId);
 
-				// Create domain for this app
+				// Create or find domain for this app
 				const isMainFrontend = isMainFrontendApp(appName, app, workspace.apps);
 				const frontendHost = resolveHost(
 					appName,
@@ -1209,43 +1605,44 @@ export async function workspaceDeployCommand(
 					isMainFrontend,
 				);
 
-				try {
-					const domain = await api.createDomain({
-						host: frontendHost,
-						port: app.port,
-						https: true,
-						certificateType: 'letsencrypt',
-						applicationId: application.applicationId,
-					});
-
-					// Track for DNS orchestration
-					appHostnames.set(appName, frontendHost);
-					appDomainIds.set(appName, domain.domainId);
+				// Check if domain already exists
+				const existingFrontendDomains = await api.getDomainsByApplicationId(
+					application.applicationId,
+				);
+				const existingFrontendDomain = existingFrontendDomains.find(
+					(d) => d.host === frontendHost,
+				);
 
-					const publicUrl = `https://${frontendHost}`;
-					publicUrls[appName] = publicUrl;
-					logger.log(`      ✓ Domain: ${publicUrl}`);
-				} catch (domainError) {
-					// Domain might already exist, try to get the existing domain
+				if (existingFrontendDomain) {
+					// Domain already exists
 					appHostnames.set(appName, frontendHost);
-
-					// Try to get existing domain ID for validation
+					appDomainIds.set(appName, existingFrontendDomain.domainId);
+					publicUrls[appName] = `https://${frontendHost}`;
+					logger.log(`      ✓ Domain: https://${frontendHost} (existing)`);
+				} else {
+					// Create new domain
 					try {
-						const existingDomains = await api.getDomainsByApplicationId(
-							application.applicationId,
-						);
-						const matchingDomain = existingDomains.find(
-							(d) => d.host === frontendHost,
-						);
-						if (matchingDomain) {
-							appDomainIds.set(appName, matchingDomain.domainId);
-						}
-					} catch {
-						// Ignore - we'll just skip validation for this domain
+						const domain = await api.createDomain({
+							host: frontendHost,
+							port: app.port,
+							https: true,
+							certificateType: 'letsencrypt',
+							applicationId: application.applicationId,
+						});
+
+						appHostnames.set(appName, frontendHost);
+						appDomainIds.set(appName, domain.domainId);
+						publicUrls[appName] = `https://${frontendHost}`;
+						logger.log(`      ✓ Domain: https://${frontendHost} (created)`);
+					} catch (domainError) {
+						const message =
+							domainError instanceof Error
+								? domainError.message
+								: 'Unknown error';
+						logger.log(`      ⚠ Domain creation failed: ${message}`);
+						appHostnames.set(appName, frontendHost);
+						publicUrls[appName] = `https://${frontendHost}`;
 					}
-
-					publicUrls[appName] = `https://${frontendHost}`;
-					logger.log(`      ℹ Domain already configured: https://${frontendHost}`);
 				}
 
 				results.push({
@@ -1258,7 +1655,8 @@ export async function workspaceDeployCommand(
 
 				logger.log(`      ✓ ${appName} deployed successfully`);
 			} catch (error) {
-				const message = error instanceof Error ? error.message : 'Unknown error';
+				const message =
+					error instanceof Error ? error.message : 'Unknown error';
 				logger.log(`      ✗ Failed to deploy ${appName}: ${message}`);
 
 				results.push({
@@ -1280,7 +1678,7 @@ export async function workspaceDeployCommand(
 	logger.log(`   ✓ State saved to .gkm/deploy-${stage}.json`);
 
 	// ==================================================================
-	// DNS: Create DNS records and validate domains for SSL
+	// DNS: Create DNS records, verify propagation, and validate for SSL
 	// ==================================================================
 	const dnsConfig = workspace.deploy.dns;
 	if (dnsConfig && appHostnames.size > 0) {
@@ -1290,6 +1688,14 @@ export async function workspaceDeployCommand(
 			creds.endpoint,
 		);
 
+		// Verify DNS records resolve correctly (with state caching)
+		if (dnsResult?.serverIp && appHostnames.size > 0) {
+			await verifyDnsRecords(appHostnames, dnsResult.serverIp, state);
+
+			// Save state again to persist DNS verification results
+			await writeStageState(workspace.root, stage, state);
+		}
+
 		// Validate domains to trigger SSL certificate generation
 		if (dnsResult?.success && appHostnames.size > 0) {
 			logger.log('\n🔒 Validating domains for SSL certificates...');