fix: support mounted .env files in container deployments (#1196)

* fix: support mounted .env files in container deployments without custom entrypoints

* test: cover env loader edge cases

Author: Bushstar

README.md

@@ -39,6 +39,14 @@ A Keychain MDIP node includes several interoperating microservices. If you follo
 
 Customize your node in the kc/.env file. Environment variables are documented for each service in the READMEs linked in the Overview above.
 
+When running the services outside `./start-node`, the supported configuration methods are:
+
+- inject environment variables directly with Docker Compose or Kubernetes
+- mount a shared `.env` file at `/app/.env` inside the container
+- mount a `.env` file anywhere and set `KC_ENV_FILE` to that path
+
+This matches local startup and avoids custom entrypoint wrappers just to source env files.
+
 ```
 KC_UID=1000                                        # Docker host UID
 KC_GID=1002                                        # Docker host GID

doc/02-server/deployment/index.mdx

@@ -219,6 +219,8 @@ Another important file controlling the behavior of an MDIP node is the `kc/docke
 
 Operators wanting to operate MDIP in a Kubernetes or similar virtualized environment will find the environment variable dependencies for each MDIP component in the `kc/docker-compose.yml` file.
 
+MDIP services support the same configuration model in container orchestration environments without custom wrapper scripts. Operators can either inject environment variables directly, mount a shared `.env` file at `/app/.env`, or mount a file elsewhere and set `KC_ENV_FILE` to the mounted path.
+
 #### Gatekeeper Service
 
 Below is the MDIP `gatekeeper` definition.
@@ -753,4 +755,3 @@ server {
         allow all;
     }
 ```
-

jest.config.js

@@ -14,6 +14,7 @@ const config = {
     moduleNameMapper: {
         '^@mdip/cipher/node$': '<rootDir>/packages/cipher/src/cipher-node.ts',
         '^@mdip/cipher/types': '<rootDir>/packages/cipher/src/types.ts',
+        '^@mdip/common/env$': '<rootDir>/packages/common/src/env.ts',
         '^@mdip/common/errors$': '<rootDir>/packages/common/src/errors.ts',
         '^@mdip/common/utils$': '<rootDir>/packages/common/src/utils.ts',
         '^@mdip/common/logger': '<rootDir>/packages/common/src/logger.ts',

package-lock.json

@@ -18,6 +18,11 @@
       "require": "./dist/cjs/index.cjs",
       "types": "./dist/types/index.d.ts"
     },
+    "./env": {
+      "import": "./dist/esm/env.js",
+      "require": "./dist/cjs/env.cjs",
+      "types": "./dist/types/env.d.ts"
+    },
     "./utils": {
       "import": "./dist/esm/utils.js",
       "require": "./dist/cjs/utils.cjs",
@@ -36,6 +41,9 @@
   },
   "typesVersions": {
     "*": {
+      "env": [
+        "./dist/types/env.d.ts"
+      ],
       "utils": [
         "./dist/types/utils.d.ts"
       ],
@@ -57,6 +65,7 @@
   "author": "David McFadzean <davidmc@gmail.com>",
   "license": "MIT",
   "dependencies": {
+    "dotenv": "^17.3.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3"
   },

packages/common/package.json

@@ -10,6 +10,7 @@ const external = [
 
 const config = {
     input: {
+        env: 'dist/esm/env.js',
         'index': 'dist/esm/index.js',
         utils: 'dist/esm/utils.js',
         errors: 'dist/esm/errors.js',

packages/common/rollup.cjs.config.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import dotenv from 'dotenv';
+
+const DEFAULT_ENV_FILENAME = '.env';
+const DEFAULT_ENV_FILE_VAR = 'KC_ENV_FILE';
+
+export interface LoadEnvOptions {
+    cwd?: string;
+    envFileVar?: string;
+    filenames?: string[];
+}
+
+function hasPackageJson(dir: string): boolean {
+    return fs.existsSync(path.join(dir, 'package.json'));
+}
+
+function hasWorkspaceRootMarker(dir: string): boolean {
+    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'docker-compose.yml'))) {
+        return true;
+    }
+
+    const packageJsonPath = path.join(dir, 'package.json');
+
+    if (!fs.existsSync(packageJsonPath)) {
+        return false;
+    }
+
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')) as { workspaces?: unknown };
+        return Array.isArray(packageJson.workspaces) || Boolean(packageJson.workspaces);
+    } catch {
+        return false;
+    }
+}
+
+function collectSearchDirectories(startDir: string): string[] {
+    const directories: string[] = [];
+    let currentDir = path.resolve(startDir);
+    let nearestPackageIndex = -1;
+
+    while (true) {
+        directories.push(currentDir);
+
+        if (nearestPackageIndex === -1 && hasPackageJson(currentDir)) {
+            nearestPackageIndex = directories.length - 1;
+        }
+
+        if (hasWorkspaceRootMarker(currentDir)) {
+            return directories;
+        }
+
+        const parentDir = path.dirname(currentDir);
+
+        if (parentDir === currentDir) {
+            break;
+        }
+
+        currentDir = parentDir;
+    }
+
+    if (nearestPackageIndex >= 0) {
+        return directories.slice(0, nearestPackageIndex + 1);
+    }
+
+    return directories;
+}
+
+export function resolveEnvFiles(options: LoadEnvOptions = {}): string[] {
+    const cwd = options.cwd ?? process.cwd();
+    const envFileVar = options.envFileVar ?? DEFAULT_ENV_FILE_VAR;
+    const filenames = options.filenames ?? [DEFAULT_ENV_FILENAME];
+    const explicitEnvFile = process.env[envFileVar]?.trim();
+    const candidates: string[] = [];
+
+    if (explicitEnvFile) {
+        const resolvedExplicitEnvFile = path.resolve(cwd, explicitEnvFile);
+
+        if (!fs.existsSync(resolvedExplicitEnvFile)) {
+            throw new Error(`Environment file set by ${envFileVar} was not found: ${resolvedExplicitEnvFile}`);
+        }
+
+        candidates.push(resolvedExplicitEnvFile);
+    }
+
+    for (const dir of collectSearchDirectories(cwd)) {
+        for (const filename of filenames) {
+            candidates.push(path.join(dir, filename));
+        }
+    }
+
+    const uniqueFiles = new Set<string>();
+
+    return candidates.filter(candidate => {
+        const resolvedCandidate = path.resolve(candidate);
+
+        if (uniqueFiles.has(resolvedCandidate)) {
+            return false;
+        }
+
+        uniqueFiles.add(resolvedCandidate);
+
+        return fs.existsSync(resolvedCandidate) && fs.statSync(resolvedCandidate).isFile();
+    });
+}
+
+export function loadEnv(options: LoadEnvOptions = {}): string[] {
+    const loadedFiles: string[] = [];
+
+    for (const envFile of resolveEnvFiles(options)) {
+        const result = dotenv.config({
+            path: envFile,
+            override: false,
+        });
+
+        if (result.error) {
+            throw result.error;
+        }
+
+        loadedFiles.push(envFile);
+    }
+
+    return loadedFiles;
+}

packages/common/src/env.ts

@@ -1,3 +1,4 @@
+export * from './env.js';
 export * from './errors.js';
 export * from './logger.js';
 export * from './utils.js';

packages/common/src/index.ts

@@ -1,10 +1,10 @@
 import express from 'express';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import dotenv from 'dotenv';
+import { loadEnv } from '@mdip/common/env';
 import { childLogger } from '@mdip/common/logger';
 
-dotenv.config();
+loadEnv();
 const log = childLogger({ service: 'explorer-server' });
 
 const __filename = fileURLToPath(import.meta.url);

services/explorer/server.js

@@ -1,6 +1,6 @@
-import dotenv from 'dotenv';
+import { loadEnv } from '@mdip/common/env';
 
-dotenv.config();
+loadEnv();
 
 const DEFAULT_RATE_LIMIT_SKIP_PATHS = ['/api/v1/ready'];