@aifabrix/builder 2.40.2 → 2.42.0

package/lib/app/run-env-compose.js

@@ -0,0 +1,264 @@
+/**
+ * Helpers for application run: clean applications dir, build merged .env, compose safeguard.
+ * Keeps run-helpers.js under line limit.
+ *
+ * @fileoverview Run env and compose helpers
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs').promises;
+const fsSync = require('fs');
+const pathsUtil = require('../utils/paths');
+const adminSecrets = require('../core/admin-secrets');
+const secretsEnvWrite = require('../core/secrets-env-write');
+const { getContainerPort } = require('../utils/port-resolver');
+const { getInfraDirName } = require('../infrastructure/helpers');
+
+/**
+ * Clean applications directory: remove generated docker-compose.yaml and .env.* files.
+ * @param {string|number} developerId - Developer ID
+ */
+function cleanApplicationsDir(developerId) {
+  const baseDir = pathsUtil.getApplicationsBaseDir(developerId);
+  if (!fsSync.existsSync(baseDir)) return;
+  const toRemove = [path.join(baseDir, 'docker-compose.yaml')];
+  try {
+    const entries = fsSync.readdirSync(baseDir);
+    for (const name of entries) {
+      if (name.startsWith('.env.')) toRemove.push(path.join(baseDir, name));
+    }
+  } catch {
+    // Ignore readdir errors
+  }
+  for (const filePath of toRemove) {
+    try {
+      if (fsSync.existsSync(filePath)) fsSync.unlinkSync(filePath);
+    } catch {
+      // Ignore unlink errors
+    }
+  }
+}
+
+/**
+ * Derive PostgreSQL user from database name (same as compose-handlebars-helpers pgUserName).
+ * @param {string} dbName - Database name (e.g. keycloak)
+ * @returns {string} User name (e.g. keycloak_user)
+ */
+function pgUserName(dbName) {
+  if (!dbName) return '';
+  return `${String(dbName).replace(/-/g, '_')}_user`;
+}
+
+/**
+ * Inject DB_N_NAME and DB_N_USER from application.yaml databases into env so .env has everything.
+ * @param {Object} env - Merged env object (mutated)
+ * @param {Object} appConfig - Application config (requires.databases or databases array)
+ */
+function injectDatabaseNamesAndUsers(env, appConfig) {
+  const databases = appConfig?.requires?.databases || appConfig?.databases;
+  if (!Array.isArray(databases) || databases.length === 0) return;
+  for (let i = 0; i < databases.length; i++) {
+    const db = databases[i];
+    const name = db?.name || (appConfig?.app?.key || 'app');
+    env[`DB_${i}_NAME`] = name;
+    env[`DB_${i}_USER`] = pgUserName(name);
+  }
+}
+
+/**
+ * Get the env var name used for PORT in env.template (e.g. PORT=${MISO_PORT} -> MISO_PORT).
+ * @param {string} appName - Application name
+ * @returns {string|null} Variable name or null if not found
+ */
+function getPortVarFromEnvTemplate(appName) {
+  const builderPath = pathsUtil.getBuilderPath(appName);
+  const templatePath = path.join(builderPath, 'env.template');
+  if (!fsSync.existsSync(templatePath)) return null;
+  try {
+    const content = fsSync.readFileSync(templatePath, 'utf8');
+    const m = content.match(/^PORT\s*=\s*\$\{([A-Za-z0-9_]+)\}/m);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Override PORT and the template's port variable (e.g. MISO_PORT) with container port from application.yaml.
+ * Run .env only: when running in Docker, the app listens on the container port (port or build.containerPort), not localPort.
+ * For envOutputPath .env (local, not reload) we use localPort instead - see adjustLocalEnvPortsInContent in secrets-helpers.
+ * @param {Object} env - Merged env object (mutated)
+ * @param {Object} appConfig - Application configuration (port, build.containerPort)
+ * @param {string} appName - Application name (to resolve env.template port var)
+ */
+function injectContainerPortForRun(env, appConfig, appName) {
+  const containerPort = getContainerPort(appConfig, 3000);
+  env.PORT = String(containerPort);
+  const portVar = getPortVarFromEnvTemplate(appName);
+  if (portVar) {
+    env[portVar] = String(containerPort);
+  }
+}
+
+/** Keys that must never be passed to the app container (admin/start-only). */
+const ADMIN_ONLY_KEYS = [
+  'POSTGRES_PASSWORD',
+  'PGADMIN_DEFAULT_EMAIL',
+  'PGADMIN_DEFAULT_PASSWORD',
+  'REDIS_HOST',
+  'REDIS_COMMANDER_USER',
+  'REDIS_COMMANDER_PASSWORD'
+];
+
+/**
+ * Build app-only env (merged minus admin secrets). App container must not receive admin passwords.
+ * @param {Object} merged - Full merged env
+ * @returns {Object} Env object safe for app container
+ */
+function buildAppOnlyEnv(merged) {
+  const appOnly = {};
+  for (const [k, v] of Object.entries(merged)) {
+    if (ADMIN_ONLY_KEYS.includes(k)) continue;
+    appOnly[k] = v;
+  }
+  return appOnly;
+}
+
+/**
+ * Build env for db-init only: POSTGRES_PASSWORD + DB_N_PASSWORD, DB_N_NAME, DB_N_USER. Used only for start, not in app container.
+ * @param {Object} merged - Full merged env
+ * @returns {Object} Env object for db-init service only
+ */
+function buildDbInitOnlyEnv(merged) {
+  const dbInit = {};
+  if (merged.POSTGRES_PASSWORD !== undefined) {
+    dbInit.POSTGRES_PASSWORD = merged.POSTGRES_PASSWORD;
+  }
+  for (const [k, v] of Object.entries(merged)) {
+    if (k.startsWith('DB_') && (k.endsWith('_PASSWORD') || k.endsWith('_NAME') || k.endsWith('_USER'))) {
+      dbInit[k] = v;
+    }
+  }
+  return dbInit;
+}
+
+/**
+ * Return pgpass paths under infra-dev* directories in aifabrix home (for fallback lookup).
+ * @param {string} aifabrixDir - Aifabrix home directory
+ * @returns {string[]} Paths to pgpass files
+ */
+function getInfraDevPgpassPaths(aifabrixDir) {
+  if (!fsSync.existsSync(aifabrixDir)) return [];
+  let entries;
+  try {
+    entries = fsSync.readdirSync(aifabrixDir).sort();
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((name) => name.startsWith('infra-dev'))
+    .map((name) => path.join(aifabrixDir, name, 'pgpass'));
+}
+
+/**
+ * Read first password from a pgpass file (format host:port:db:user:password).
+ * @param {string} pgpassPath - Path to pgpass file
+ * @returns {Promise<string|undefined>} Password or undefined
+ */
+async function readPasswordFromPgpassFile(pgpassPath) {
+  const content = await fs.readFile(pgpassPath, 'utf8');
+  const line = content.split('\n')[0];
+  if (!line) return undefined;
+  const parts = line.split(':');
+  return parts.length >= 5 ? parts[4].trim() : undefined;
+}
+
+/**
+ * Read POSTGRES_PASSWORD from an existing infra pgpass so db-init uses the same password as running Postgres.
+ * Tries dev-specific, then default infra, then any infra-dev* dir (e.g. dev 1 run when only infra-dev06 has pgpass).
+ * @param {number|string} developerId - Developer ID
+ * @returns {Promise<string|undefined>} Password or undefined
+ */
+async function readPostgresPasswordFromPgpass(developerId) {
+  const home = pathsUtil.getAifabrixHome();
+  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const candidates = [path.join(home, getInfraDirName(developerId), 'pgpass')];
+  if (idNum !== 0) candidates.push(path.join(home, getInfraDirName(0), 'pgpass'));
+  const extra = getInfraDevPgpassPaths(home).filter((p) => !candidates.includes(p));
+  candidates.push(...extra);
+  for (const pgpassPath of candidates) {
+    if (!fsSync.existsSync(pgpassPath)) continue;
+    try {
+      const pwd = await readPasswordFromPgpassFile(pgpassPath);
+      if (pwd !== undefined) return pwd;
+    } catch {
+      // ignore
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Build two run env files: .env.run (app-only, no admin secrets) and .env.run.admin (start-only, for db-init).
+ * Admin password is never set in the app container; .env.run.admin is used only for start and then deleted.
+ * When an infra pgpass exists, POSTGRES_PASSWORD is taken from it so db-init matches the running Postgres.
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} appConfig - Application configuration
+ * @param {string} devDir - Applications directory path
+ * @param {number|string} [developerId] - Developer ID (for pgpass lookup)
+ * @returns {Promise<{ runEnvPath: string, runEnvAdminPath: string }>} Paths to .env.run and .env.run.admin
+ */
+async function buildMergedRunEnvAndWrite(appName, appConfig, devDir, developerId) {
+  const infra = require('../infrastructure');
+  const ensureAdminSecretsFn = typeof infra.ensureAdminSecrets === 'function'
+    ? infra.ensureAdminSecrets
+    : require('../infrastructure/helpers').ensureAdminSecrets;
+  await ensureAdminSecretsFn();
+  const adminObj = await adminSecrets.readAndDecryptAdminSecrets();
+  const appObj = await secretsEnvWrite.resolveAndGetEnvMap(appName, {
+    environment: 'docker',
+    secretsPath: null,
+    force: false
+  });
+  const merged = { ...adminObj, ...appObj };
+  if (developerId !== undefined) {
+    const pgpassPwd = await readPostgresPasswordFromPgpass(developerId);
+    if (pgpassPwd !== undefined) merged.POSTGRES_PASSWORD = pgpassPwd;
+  }
+  injectDatabaseNamesAndUsers(merged, appConfig);
+  injectContainerPortForRun(merged, appConfig, appName);
+
+  const runEnvPath = path.join(devDir, '.env.run');
+  const runEnvAdminPath = path.join(devDir, '.env.run.admin');
+
+  const appOnly = buildAppOnlyEnv(merged);
+  const dbInitOnly = buildDbInitOnlyEnv(merged);
+
+  await fs.writeFile(runEnvPath, adminSecrets.envObjectToContent(appOnly), { mode: 0o600 });
+  await fs.writeFile(runEnvAdminPath, adminSecrets.envObjectToContent(dbInitOnly), { mode: 0o600 });
+
+  return { runEnvPath, runEnvAdminPath };
+}
+
+/**
+ * Assert generated compose does not contain password literals in environment (ISO 27K).
+ * @param {string} composeContent - Generated docker-compose content
+ * @throws {Error} If password keys appear in environment-like assignment
+ */
+function assertNoPasswordLiteralsInCompose(composeContent) {
+  const badPattern = /\n\s+(-?\s*)(POSTGRES_PASSWORD|DB_\d+_PASSWORD)\s*[:=]/;
+  if (badPattern.test(composeContent)) {
+    throw new Error('Generated compose must not contain password literals (POSTGRES_PASSWORD, DB_*_PASSWORD). Use env_file only.');
+  }
+}
+
+module.exports = {
+  cleanApplicationsDir,
+  buildMergedRunEnvAndWrite,
+  assertNoPasswordLiteralsInCompose
+};

package/lib/app/run-helpers.js

@@ -17,8 +17,6 @@ const { exec } = require('child_process');
 const { loadConfigFile } = require('../utils/config-format');
 const { promisify } = require('util');
 const validator = require('../validation/validator');
-const infra = require('../infrastructure');
-const secrets = require('../core/secrets');
 const config = require('../core/config');
 const buildCopy = require('../utils/build-copy');
 const logger = require('../utils/logger');
@@ -27,7 +25,10 @@ const composeGenerator = require('../utils/compose-generator');
 const dockerUtils = require('../utils/docker');
 const containerHelpers = require('../utils/app-run-containers');
 const pathsUtil = require('../utils/paths');
+const runEnvCompose = require('./run-env-compose');
+const { resolveEnvOutputPath, writeEnvOutputForReload, writeEnvOutputForLocal } = require('../utils/env-copy');
 const { resolveVersionForApp } = require('../utils/image-version');
+const { parseImageOverride } = require('../utils/parse-image-ref');
 
 const execAsync = promisify(exec);
 
@@ -160,6 +161,28 @@ async function resolveAndUpdateVersion(appName, appConfig, debug) {
   }
 }
 
+/**
+ * Resolve image name and tag from app config and optional run override.
+ * @param {string} appName - Application name
+ * @param {Object} appConfig - Application configuration
+ * @param {Object} runOptions - Run options; runOptions.image overrides config
+ * @returns {{ imageName: string, imageTag: string }} imageName and imageTag
+ */
+function resolveRunImage(appName, appConfig, runOptions) {
+  const imageOverride = runOptions && runOptions.image;
+  if (imageOverride) {
+    const parsed = parseImageOverride(imageOverride);
+    return {
+      imageName: parsed ? parsed.name : composeGenerator.getImageName(appConfig, appName),
+      imageTag: parsed ? parsed.tag : (appConfig.image && appConfig.image.tag) || 'latest'
+    };
+  }
+  return {
+    imageName: composeGenerator.getImageName(appConfig, appName),
+    imageTag: (appConfig.image && appConfig.image.tag) || 'latest'
+  };
+}
+
 /**
  * Checks prerequisites: Docker image and (optionally) infrastructure
  * @async
@@ -167,11 +190,11 @@ async function resolveAndUpdateVersion(appName, appConfig, debug) {
  * @param {Object} appConfig - Application configuration
  * @param {boolean} [debug=false] - Enable debug logging
  * @param {boolean} [skipInfraCheck=false] - When true, skip infra health check (e.g. when caller already verified, e.g. up-miso)
+ * @param {Object} [runOptions] - Run options; when runOptions.image is set, that image is checked instead of config-derived
  * @throws {Error} If prerequisites are not met
  */
-async function checkPrerequisites(appName, appConfig, debug = false, skipInfraCheck = false) {
-  const imageName = composeGenerator.getImageName(appConfig, appName);
-  const imageTag = appConfig.image?.tag || 'latest';
+async function checkPrerequisites(appName, appConfig, debug = false, skipInfraCheck = false, runOptions = {}) {
+  const { imageName, imageTag } = resolveRunImage(appName, appConfig, runOptions);
   const fullImageName = `${imageName}:${imageTag}`;
 
   if (debug) {
@@ -181,7 +204,11 @@ async function checkPrerequisites(appName, appConfig, debug = false, skipInfraCh
   logger.log(chalk.blue(`Checking if image ${fullImageName} exists...`));
   const imageExists = await checkImageExists(imageName, imageTag, debug);
   if (!imageExists) {
-    throw new Error(`Docker image ${fullImageName} not found\nRun 'aifabrix build ${appName}' first`);
+    const isTemplateApp = TEMPLATE_APP_KEYS.includes(appName);
+    const hint = isTemplateApp
+      ? `Pull the image (e.g. docker pull ${fullImageName}) or use --image ${appName}=<image> for up-miso/up-dataplane.`
+      : `Run 'aifabrix build ${appName}' first`;
+    throw new Error(`Docker image ${fullImageName} not found\n${hint}`);
   }
   logger.log(chalk.green(`✓ Image ${fullImageName} found`));
 
@@ -200,6 +227,7 @@ async function checkPrerequisites(appName, appConfig, debug = false, skipInfraCh
  */
 async function checkInfraHealthOrThrow(debug) {
   logger.log(chalk.blue('Checking infrastructure health...'));
+  const infra = require('../infrastructure');
   const infraHealth = await infra.checkInfraHealth();
   if (debug) {
     logger.log(chalk.gray(`[DEBUG] Infrastructure health: ${JSON.stringify(infraHealth, null, 2)}`));
@@ -230,73 +258,20 @@ async function ensureDevDirectory(appName, developerId) {
 }
 
 /**
- * Generate or update .env file for Docker
- * @async
- * @param {string} appName - Application name
- * @param {string} builderEnvPath - Path to builder .env file
- * @param {boolean} [skipOutputPath=false] - When true, skip copying to envOutputPath (e.g. up-miso/up-dataplane, no local code)
- */
-async function ensureEnvFile(appName, builderEnvPath, skipOutputPath = false) {
-  if (!fsSync.existsSync(builderEnvPath)) {
-    logger.log(chalk.yellow('Generating .env file from template...'));
-    await secrets.generateEnvFile(appName, null, 'docker', false, skipOutputPath);
-  } else {
-    logger.log(chalk.blue('Updating .env file for Docker environment...'));
-    await secrets.generateEnvFile(appName, null, 'docker', false, skipOutputPath);
-  }
-}
-
-/**
- * Copy .env file to dev directory
- * @async
- * @param {string} builderEnvPath - Path to builder .env file
- * @param {string} devEnvPath - Path to dev .env file
- */
-async function copyEnvToDev(builderEnvPath, devEnvPath) {
-  if (fsSync.existsSync(builderEnvPath)) {
-    await fs.copyFile(builderEnvPath, devEnvPath);
-  }
-}
-
-/**
- * Handle envOutputPath configuration
- * @async
- * @param {string} appName - Application name
- * @param {string} configPath - Path to application config file
- * @param {string} builderEnvPath - Path to builder .env file
- * @param {string} devEnvPath - Path to dev .env file
- * @param {boolean} [skipOutputPath=false] - When true, skip (e.g. up-miso/up-dataplane, no local code)
- */
-async function handleEnvOutputPath(appName, configPath, builderEnvPath, devEnvPath, skipOutputPath = false) {
-  if (skipOutputPath) {
-    return;
-  }
-  let variables;
-  try {
-    variables = loadConfigFile(configPath);
-  } catch {
-    return;
-  }
-
-  if (variables?.build?.envOutputPath && variables.build.envOutputPath !== null) {
-    logger.log(chalk.blue('Ensuring .env file in apps/ directory is updated for Docker...'));
-    await secrets.generateEnvFile(appName, null, 'docker');
-    await copyEnvToDev(builderEnvPath, devEnvPath);
-  }
-}
-
-/**
- * Calculate compose port from options or app config
- * @param {Object} options - Run options
+ * Calculate host port for docker-compose mapping (first port in "host:container").
+ * Uses application.yaml top-level port (not localPort). Second port is always containerPort from config.
+ * Example: keycloak port 8082, containerPort 8080 → "8082:8080"; miso-controller port 3000 → "3000:3000".
+ *
+ * @param {Object} options - Run options (may include port override)
  * @param {Object} appConfig - Application configuration
  * @param {string} developerId - Developer ID
- * @returns {number} Port number
+ * @returns {number} Host port number
  */
 function calculateComposePort(options, appConfig, developerId) {
   if (options.port) {
     return options.port;
   }
-  const basePort = appConfig.port || 3000;
+  const basePort = appConfig.port ?? 3000;
   const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
   return idNum === 0 ? basePort : basePort + (idNum * 100);
 }
@@ -313,84 +288,104 @@ function calculateComposePort(options, appConfig, developerId) {
 async function generateComposeFile(appName, appConfig, composeOptions, devDir) {
   logger.log(chalk.blue('Generating Docker Compose configuration...'));
   const composeContent = await composeGenerator.generateDockerCompose(appName, appConfig, composeOptions);
+  runEnvCompose.assertNoPasswordLiteralsInCompose(composeContent);
   const tempComposePath = path.join(devDir, 'docker-compose.yaml');
   await fs.writeFile(tempComposePath, composeContent);
   return tempComposePath;
 }
 
 /**
- * Prepares environment: ensures .env file and generates Docker Compose
+ * Writes .env to envOutputPath when application.yaml build.envOutputPath is set.
  * @async
  * @param {string} appName - Application name
  * @param {Object} appConfig - Application configuration
- * @param {Object} options - Run options
- * @returns {Promise<string>} Path to generated compose file
+ * @param {string} runEnvPath - Path to .env.run
+ * @param {Object} options - Run options (reload flag)
+ */
+async function writeEnvOutputIfConfigured(appName, appConfig, runEnvPath, options) {
+  if (options && options.skipEnvOutputPath === true) return;
+  const envOutputPathRaw = appConfig.build?.envOutputPath;
+  if (!envOutputPathRaw || typeof envOutputPathRaw !== 'string' || envOutputPathRaw.trim() === '') {
+    return;
+  }
+  const configPath = path.join(pathsUtil.getBuilderPath(appName), 'application.yaml');
+  const outputPath = resolveEnvOutputPath(envOutputPathRaw.trim(), configPath);
+  const outputDir = path.dirname(outputPath);
+  if (!fsSync.existsSync(outputDir)) {
+    await fs.mkdir(outputDir, { recursive: true });
+  }
+  if (options.reload) {
+    await writeEnvOutputForReload(outputPath, runEnvPath);
+  } else {
+    await writeEnvOutputForLocal(appName, outputPath);
+  }
+}
+
+/**
+ * Prepares environment: clean applications dir, build two .env files (app-only + start-only), generate Docker Compose.
+ * .env.run = app container only (no admin secrets). .env.run.admin = db-init/start only (POSTGRES_PASSWORD etc.), deleted after run.
+ *
+ * @async
+ * @param {string} appName - Application name
+ * @param {Object} appConfig - Application configuration
+ * @param {Object} options - Run options (may include envFilePath, devMountPath from caller)
+ * @returns {Promise<{ composePath: string, runEnvPath: string, runEnvAdminPath: string }>} Paths to compose and both run .env files (delete after success)
  */
 async function prepareEnvironment(appName, appConfig, options) {
   const developerId = await config.getDeveloperId();
   const devDir = await ensureDevDirectory(appName, developerId);
-  const skipEnvOutputPath = options.skipEnvOutputPath === true;
 
-  // Generate/update .env file (respect AIFABRIX_BUILDER_DIR when set by up-miso/up-dataplane)
-  const builderEnvPath = path.join(pathsUtil.getBuilderPath(appName), '.env');
-  await ensureEnvFile(appName, builderEnvPath, skipEnvOutputPath);
+  runEnvCompose.cleanApplicationsDir(developerId);
+  logger.log(chalk.blue('Building merged .env (admin + app secrets)...'));
+  const { runEnvPath, runEnvAdminPath } = await runEnvCompose.buildMergedRunEnvAndWrite(appName, appConfig, devDir, developerId);
 
-  // Copy .env to dev directory
-  const devEnvPath = path.join(devDir, '.env');
-  await copyEnvToDev(builderEnvPath, devEnvPath);
+  const composeOptions = {
+    ...options,
+    envFilePath: runEnvPath,
+    dbInitEnvFilePath: runEnvAdminPath
+  };
+  composeOptions.port = calculateComposePort(composeOptions, appConfig, developerId);
+  const composePath = await generateComposeFile(appName, appConfig, composeOptions, devDir);
 
-  // Handle envOutputPath if configured (skipped when skipEnvOutputPath e.g. up-miso/up-dataplane)
-  let configPath;
-  try {
-    configPath = pathsUtil.resolveApplicationConfigPath(devDir);
-  } catch {
-    configPath = null;
-  }
-  if (configPath) {
-    await handleEnvOutputPath(appName, configPath, builderEnvPath, devEnvPath, skipEnvOutputPath);
-  }
+  await writeEnvOutputIfConfigured(appName, appConfig, runEnvPath, options);
 
-  // Generate Docker Compose
-  const composeOptions = { ...options };
-  composeOptions.port = calculateComposePort(composeOptions, appConfig, developerId);
-  return await generateComposeFile(appName, appConfig, composeOptions, devDir);
+  return { composePath, runEnvPath, runEnvAdminPath };
 }
 
 /**
- * Prepare environment variables from admin secrets
+ * Prepare environment variables for docker compose (no secrets in host env; compose uses env_file).
  * @async
  * @param {boolean} debug - Enable debug logging
- * @returns {Promise<Object>} Environment variables object
+ * @returns {Promise<Object>} Environment variables object for child process
  */
 async function prepareContainerEnv(debug) {
-  const adminSecretsPath = await infra.ensureAdminSecrets();
-  if (debug) {
-    logger.log(chalk.gray(`[DEBUG] Admin secrets path: ${adminSecretsPath}`));
-  }
+  const env = { ...process.env };
 
-  const adminSecretsContent = fsSync.readFileSync(adminSecretsPath, 'utf8');
-  const postgresPasswordMatch = adminSecretsContent.match(/^POSTGRES_PASSWORD=(.+)$/m);
-  const postgresPassword = postgresPasswordMatch ? postgresPasswordMatch[1] : '';
+  if (typeof process.getuid === 'function' && typeof process.getgid === 'function') {
+    env.AIFABRIX_UID = String(process.getuid());
+    env.AIFABRIX_GID = String(process.getgid());
+  } else {
+    env.AIFABRIX_UID = '1000';
+    env.AIFABRIX_GID = '1000';
+  }
 
-  const env = {
-    ...process.env,
-    ADMIN_SECRETS_PATH: adminSecretsPath,
-    POSTGRES_PASSWORD: postgresPassword
-  };
+  const { getRemoteDockerEnv } = require('../utils/remote-docker-env');
+  const remoteDocker = await getRemoteDockerEnv();
+  Object.assign(env, remoteDocker);
 
   if (debug) {
-    logger.log(chalk.gray(`[DEBUG] Environment variables: ADMIN_SECRETS_PATH=${adminSecretsPath}, POSTGRES_PASSWORD=${postgresPassword ? '***' : '(not set)'}`));
+    logger.log(chalk.gray('[DEBUG] Container env prepared (secrets via env_file)'));
   }
 
   return env;
 }
 
 /**
- * Execute docker-compose up command
+ * Execute docker-compose up command. Services get env from env_file in the compose (e.g. .env.run).
  * @async
  * @param {string} composeCmdBase - Base compose command
  * @param {string} composePath - Path to compose file
- * @param {Object} env - Environment variables
+ * @param {Object} env - Environment variables for the child process
  * @param {boolean} debug - Enable debug logging
  */
 async function executeComposeUp(composeCmdBase, composePath, env, debug) {
@@ -403,37 +398,44 @@ async function executeComposeUp(composeCmdBase, composePath, env, debug) {
 }
 
 /**
- * Starts the container and waits for health check
+ * Starts the container and waits for health check. Deletes run .env files after success (ISO 27K).
  * @async
  * @param {string} appName - Application name
  * @param {string} composePath - Path to Docker Compose file
  * @param {number} port - Application port
  * @param {Object} appConfig - Application configuration
- * @param {boolean} [debug=false] - Enable debug logging
+ * @param {Object} [opts] - Options
+ * @param {boolean} [opts.debug=false] - Enable debug logging
+ * @param {string|null} [opts.runEnvPath=null] - Path to .env.run (app-only) to delete after successful start
+ * @param {string|null} [opts.runEnvAdminPath=null] - Path to .env.run.admin (start-only) to delete after successful start
  * @throws {Error} If container fails to start or become healthy
  */
-async function startContainer(appName, composePath, port, appConfig = null, debug = false) {
+async function startContainer(appName, composePath, port, appConfig = null, opts = {}) {
+  const { debug = false, runEnvPath = null, runEnvAdminPath = null } = opts;
   logger.log(chalk.blue(`Starting ${appName}...`));
 
-  // Ensure Docker + Compose available and determine correct compose command
   const composeCmdBase = await dockerUtils.ensureDockerAndCompose().then(() => dockerUtils.getComposeCommand());
-
-  // Prepare environment variables
   const env = await prepareContainerEnv(debug);
-
-  // Execute compose up
   await executeComposeUp(composeCmdBase, composePath, env, debug);
 
-  // Get container name and log status
   const idNum = typeof appConfig.developerId === 'string' ? parseInt(appConfig.developerId, 10) : appConfig.developerId;
   const containerName = idNum === 0 ? `aifabrix-${appName}` : `aifabrix-dev${appConfig.developerId}-${appName}`;
   logger.log(chalk.green(`✓ Container ${containerName} started`));
   await containerHelpers.logContainerStatus(containerName, debug);
 
-  // Wait for health check
   const healthCheckPath = appConfig?.healthCheck?.path || '/health';
   logger.log(chalk.blue(`Waiting for application to be healthy at http://localhost:${port}${healthCheckPath}...`));
   await waitForHealthCheck(appName, 90, port, appConfig, debug);
+
+  for (const p of [runEnvPath, runEnvAdminPath]) {
+    if (p && typeof p === 'string') {
+      try {
+        await fs.unlink(p);
+      } catch (err) {
+        if (err.code !== 'ENOENT') logger.log(chalk.yellow(`Warning: could not remove run .env: ${err.message}`));
+      }
+    }
+  }
 }
 
 /**
@@ -461,6 +463,7 @@ module.exports = {
   checkPrerequisites,
   prepareEnvironment,
   startContainer,
-  displayRunStatus
+  displayRunStatus,
+  cleanApplicationsDir: runEnvCompose.cleanApplicationsDir
 };