Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: make PM2 honor an exported PGMODE like database setup does (#10758)

Adam Eivy58adf7b0abb0
diff --git a/docs/SETUP.md b/docs/SETUP.md
index ea65648a69..3d6cd83878 100644
--- a/docs/SETUP.md
+++ b/docs/SETUP.md
@@ -22,7 +22,7 @@ Docker and native PostgreSQL.
endpoint and, if it is not ready, invokes the native bootstrap in
`scripts/db.sh setup-native` (Homebrew provisioning).
-An exported `PGMODE` overrides `.env`; unset a conflicting shell value before
+A nonempty exported `PGMODE` overrides `.env`; an empty one counts as unset. Setup and PM2 (`ecosystem.config.cjs`) share this precedence; unset a conflicting shell value before
setup. If Docker is selected but unavailable, setup fails even if native
PostgreSQL is healthy. It leaves the selection unchanged so a missing Docker
daemon cannot silently redirect an existing install to another database.
diff --git a/docs/STORAGE.md b/docs/STORAGE.md
index 4f0b494545..7973041cf7 100644
--- a/docs/STORAGE.md
+++ b/docs/STORAGE.md
@@ -367,7 +367,7 @@ PortOS treats **PostgreSQL as a mandatory install/runtime dependency** for every
- **System (native) PostgreSQL on `:5432`** — `PGMODE=native`, or
- **Docker PostgreSQL on `:5561`** — `PGMODE=docker` (the default).
-Provision either path with **`npm run setup:db`** (also run automatically by `npm run setup` and `npm start`). It follows `PGMODE` (shell environment → `.env` → `docker`), and provisions only that selected backend. An unavailable Docker installation fails setup without probing native PostgreSQL or changing the saved mode. See [Setup path](#setup-path-npm-run-setupdb) below.
+Provision either path with **`npm run setup:db`** (also run automatically by `npm run setup` and `npm start`). It follows `PGMODE` (nonempty shell export → `.env` → `docker`; an empty export is unset) — the same precedence `ecosystem.config.cjs` uses to pick the managed processes' `PGPORT`, so setup and PM2 never disagree — and provisions only that selected backend. An unavailable Docker installation fails setup without probing native PostgreSQL or changing the saved mode. See [Setup path](#setup-path-npm-run-setupdb) below.
The standalone `scripts/db.sh` also reads the repository-root `.env` through the
shared setup parser (Node is required), with nonempty shell settings taking
diff --git a/ecosystem.config.cjs b/ecosystem.config.cjs
index a3b15fd8de..585308876c 100644
--- a/ecosystem.config.cjs
+++ b/ecosystem.config.cjs
@@ -25,7 +25,10 @@ const envFile = path.join(__dirname, '.env');
const { parseEnvFile } = require('./scripts/lib/envFile.cjs');
const dotenv = parseEnvFile(envFile); // {} when .env is missing
const envValue = (key) => dotenv[key] || null;
-const pgMode = envValue('PGMODE') || 'docker';
+// Same precedence as scripts/setup-db.js getMode(): a NONEMPTY exported PGMODE →
+// saved .env → docker, so setup and PM2 always provision/dial the same backend
+// (#10758). An empty export is unset, never a third mode.
+const pgMode = process.env.PGMODE || envValue('PGMODE') || 'docker';
const envServerMaxMemory = envValue('PORTOS_SERVER_MAX_MEMORY');
const envPgPassword = envValue('PGPASSWORD');
const envPgUser = envValue('PGUSER');
diff --git a/scripts/ecosystemEnv.test.js b/scripts/ecosystemEnv.test.js
index cf06fca57d..9b86a26105 100644
--- a/scripts/ecosystemEnv.test.js
+++ b/scripts/ecosystemEnv.test.js
@@ -202,4 +202,36 @@ describe('ecosystem.config.cjs parses .env with the setup grammar (#9471)', () =
expect(config.DATABASE_MODE).toBe('docker');
expect(server(config).env.PGPORT).toBe(5561);
});
+ describe('mode precedence matches setup (#10758)', () => {
+ const ports = 'PGPORT=5433\nPGPORT_DOCKER=5570\n';
+ it.each([
+ ['docker', 'native', 5433],
+ ['native', 'docker', 5570],
+ ])('saved %s with exported %s resolves to the exported mode and port %i', (saved, exported, port) => {
+ const config = loadConfig(`PGMODE=${saved}\n${ports}`, { ...clearedPgEnv, PGMODE: exported });
+ expect(config.DATABASE_MODE).toBe(exported);
+ for (const name of ['portos-server', 'portos-cos']) {
+ expect(config.apps.find((a) => a.name === name).env.PGPORT).toBe(port);
+ }
+ expect(config.DATABASE_ENDPOINTS.native.port).toBe(5433);
+ expect(config.DATABASE_ENDPOINTS.docker.port).toBe(5570);
+ });
+
+ it('treats an empty exported PGMODE as unset and uses the saved mode', () => {
+ const config = loadConfig(`PGMODE=native\n${ports}`, { ...clearedPgEnv, PGMODE: '' });
+ expect(config.DATABASE_MODE).toBe('native');
+ expect(server(config).env.PGPORT).toBe(5433);
+ });
+
+ it('falls back to docker when the export is empty and no .env is saved', () => {
+ const config = loadConfig(null, { ...clearedPgEnv, PGMODE: '' });
+ expect(config.DATABASE_MODE).toBe('docker');
+ });
+
+ it('lets an exported mode apply with no saved .env', () => {
+ const config = loadConfig(null, { ...clearedPgEnv, PGMODE: 'native' });
+ expect(config.DATABASE_MODE).toBe('native');
+ expect(server(config).env.PGPORT).toBe(5432);
+ });
+ });
});
diff --git a/scripts/setup-db.js b/scripts/setup-db.js
index 2e9f0176fc..2337f16352 100644
--- a/scripts/setup-db.js
+++ b/scripts/setup-db.js
@@ -54,7 +54,8 @@ const PG_CHILD_ENV = {
};
function getMode() {
- return envVar('PGMODE', 'docker');
+ // Nonempty exported PGMODE → .env → docker; must match ecosystem.config.cjs (#10758).
+ return process.env.PGMODE || envFile.PGMODE || 'docker';
}
// Check if Docker is available
diff --git a/scripts/setup-db.test.js b/scripts/setup-db.test.js
index c3494cb9f2..4a3f6643a6 100644
--- a/scripts/setup-db.test.js
+++ b/scripts/setup-db.test.js
@@ -64,7 +64,7 @@ describe('native setup inherited endpoint', () => {
// Run the actual CLI body with synthetic configuration and subprocesses. No
// imports execute, no install .env is read, and no database can be contacted.
-async function runSetup({ mode = 'docker', unavailable, tty = false, nativeReady = true, running = true, hostBinding = '127.0.0.1', hostPort = 5561, dotEnv = {} } = {}) {
+async function runSetup({ mode = 'docker', unavailable, tty = false, nativeReady = true, running = true, hostBinding = '127.0.0.1', hostPort = 5561, dotEnv = {}, exportedMode } = {}) {
const savedEnv = { PGMODE: mode, EXAMPLE_SETTING: 'preserved', ...dotEnv };
const initialEnv = { ...savedEnv };
const calls = [];
@@ -89,7 +89,7 @@ async function runSetup({ mode = 'docker', unavailable, tty = false, nativeReady
createInterface: () => { throw new Error('Setup must not prompt to switch backends'); },
resolveBashBinary: () => 'bash',
process: {
- env: {}, platform: 'linux', stdin: { isTTY: tty }, stdout: { isTTY: tty },
+ env: exportedMode === undefined ? {} : { PGMODE: exportedMode }, platform: 'linux', stdin: { isTTY: tty }, stdout: { isTTY: tty },
exit: (code) => { exitCode = code; throw exitSignal; }
},
console: { log: (message) => logs.push(message), error: (message) => errors.push(message) },
@@ -211,4 +211,15 @@ describe('setup preserves the selected database', () => {
const setupIndex = result.calls.findIndex((call) => call.includes('setup-native'));
expect(result.childEnvs[setupIndex]).toMatchObject({ PGHOST: 'db.example.invalid', PGPORT: '5433' });
});
+ // Pairs with scripts/ecosystemEnv.test.js "mode precedence matches setup" (#10758).
+ it.each([
+ ['docker', 'native', true],
+ ['native', 'docker', false],
+ ['native', '', true],
+ ])('saved %s with exported %j selects the same backend PM2 does', async (mode, exportedMode, expectNative) => {
+ const result = await runSetup({ mode, exportedMode, nativeReady: true });
+ expect(result.exitCode).toBe(0);
+ expect(result.calls.some(([command]) => command === 'psql')).toBe(expectNative);
+ expect(result.calls.some(([command]) => command === 'docker')).toBe(!expectNative);
+ });
});