fix(sim-setup): persist a shell POSTGRES_PASSWORD and rotate the effective role

A password exported only in the shell is now written to .env, so a later run without the export does not fall back to the legacy value. Rotation steps use the install's POSTGRES_USER and ALTER ROLE CURRENT_USER.

Author: waleedlatif1

apps/docs/content/docs/platform/self-hosting/security.mdx

@@ -279,7 +279,7 @@ The Compose files do not publish the `db` service to the host: `simstudio`, `rea
   Installs created from an earlier Compose file published the database on every interface of the host (`5432:5432`), and a `POSTGRES_PASSWORD` left unset fell back to `postgres`. A Docker `ports:` mapping writes its own iptables rules, so a host firewall that looks like it blocks 5432 usually does not. Update the Compose file, then check what your database was created with:
 
   - **You set `POSTGRES_PASSWORD` before the first start.** Nothing else to do — updating the file closes the port.
-  - **You never set it.** Postgres applies `POSTGRES_PASSWORD` only when it creates the data volume, so the database still uses `postgres`. Set `POSTGRES_PASSWORD=postgres` in `.env` so the stack starts, then rotate it: run `docker compose -f docker-compose.prod.yml exec db psql -U postgres -c "ALTER ROLE postgres PASSWORD '<new password>'"`, set `POSTGRES_PASSWORD` to the same value, and run `docker compose -f docker-compose.prod.yml up -d`. Setting a new value in `.env` alone does not change the database's password and locks the app out.
+  - **You never set it.** Postgres applies `POSTGRES_PASSWORD` only when it creates the data volume, so the database still uses `postgres`. Set `POSTGRES_PASSWORD=postgres` in `.env` so the stack starts, then rotate it: run `docker compose -f docker-compose.prod.yml exec db psql -U postgres -c "ALTER ROLE CURRENT_USER PASSWORD '<new password>'"` (with your `POSTGRES_USER` in place of `postgres` if you set one), set `POSTGRES_PASSWORD` to the same value, and run `docker compose -f docker-compose.prod.yml up -d`. Setting a new value in `.env` alone does not change the database's password and locks the app out.
 
   `npx sim-setup start` and `npx sim-setup update` write the right value for you and print the rotation steps.
 </Callout>

packages/sim-setup/src/compose-database.test.ts

@@ -5,8 +5,8 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
   choosePostgresPassword,
   composeFileRequiresPostgresPassword,
-  configuredPostgresPassword,
   LEGACY_POSTGRES_PASSWORD,
+  postgresUser,
 } from './compose-database'
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..')
@@ -34,37 +34,57 @@ afterEach(() => {
 })
 
 describe('choosePostgresPassword', () => {
-  it('leaves a configured password alone without looking for a volume', () => {
-    const lookup = vi.fn(() => true)
-    expect(choosePostgresPassword('already-set', 'sim-abc', lookup)).toBeNull()
-    expect(lookup).not.toHaveBeenCalled()
+  it('leaves a password already in .env alone without looking for a volume', () => {
+    const hasDatabaseVolume = vi.fn(() => true)
+    expect(
+      choosePostgresPassword('in-env-file', 'sim-abc', {
+        shellValue: 'in-shell',
+        hasDatabaseVolume,
+      })
+    ).toBeNull()
+    expect(hasDatabaseVolume).not.toHaveBeenCalled()
+  })
+
+  it('persists a shell-exported password, which is what Compose is using', () => {
+    const hasDatabaseVolume = vi.fn(() => true)
+    expect(
+      choosePostgresPassword(undefined, 'sim-abc', { shellValue: 'in-shell', hasDatabaseVolume })
+    ).toEqual({ value: 'in-shell', source: 'environment' })
+    expect(hasDatabaseVolume).not.toHaveBeenCalled()
   })
 
   it('generates a password for a project with no database volume yet', () => {
-    const lookup = vi.fn(() => false)
-    const choice = choosePostgresPassword(undefined, 'sim-abc', lookup)
-    expect(lookup).toHaveBeenCalledWith('sim-abc')
-    expect(choice?.legacy).toBe(false)
+    const hasDatabaseVolume = vi.fn(() => false)
+    const choice = choosePostgresPassword('', 'sim-abc', { shellValue: '', hasDatabaseVolume })
+    expect(hasDatabaseVolume).toHaveBeenCalledWith('sim-abc')
+    expect(choice?.source).toBe('generated')
     expect(choice?.value).toMatch(/^[0-9a-f]{64}$/)
   })
 
   it('keeps the legacy password for a volume created before it was required', () => {
-    const choice = choosePostgresPassword(undefined, 'sim-abc', () => true)
-    expect(choice).toEqual({ value: LEGACY_POSTGRES_PASSWORD, legacy: true })
+    expect(
+      choosePostgresPassword(undefined, 'sim-abc', {
+        shellValue: '',
+        hasDatabaseVolume: () => true,
+      })
+    ).toEqual({ value: LEGACY_POSTGRES_PASSWORD, source: 'legacy' })
   })
-})
 
-describe('configuredPostgresPassword', () => {
-  it('prefers the shell environment, which Compose interpolates over .env', () => {
-    vi.stubEnv('POSTGRES_PASSWORD', 'from-shell')
-    expect(configuredPostgresPassword('from-env-file')).toBe('from-shell')
+  it('reads the shell environment by default', () => {
+    vi.stubEnv('POSTGRES_PASSWORD', 'from-process')
+    expect(choosePostgresPassword(undefined, 'sim-abc', { hasDatabaseVolume: () => true })).toEqual(
+      { value: 'from-process', source: 'environment' }
+    )
   })
+})
 
-  it('falls back to .env and treats empty values as unset', () => {
-    vi.stubEnv('POSTGRES_PASSWORD', '')
-    expect(configuredPostgresPassword('from-env-file')).toBe('from-env-file')
-    expect(configuredPostgresPassword('')).toBeUndefined()
-    expect(configuredPostgresPassword(undefined)).toBeUndefined()
+describe('postgresUser', () => {
+  it('prefers the shell, then .env, then the image default', () => {
+    vi.stubEnv('POSTGRES_USER', 'from-shell')
+    expect(postgresUser('from-env-file')).toBe('from-shell')
+    vi.stubEnv('POSTGRES_USER', '')
+    expect(postgresUser('from-env-file')).toBe('from-env-file')
+    expect(postgresUser(undefined)).toBe('postgres')
   })
 })
 

packages/sim-setup/src/compose-database.ts

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 import { generateSecret } from './env-files'
 import { SetupError } from './errors'
+import * as p from './prompter'
 
 /**
  * The password Postgres was initialized with on a Compose install created while
@@ -23,37 +24,45 @@ export function composeFileRequiresPostgresPassword(composeFile: string): boolea
   return readFileSync(composeFile, 'utf8').includes('${POSTGRES_PASSWORD:?')
 }
 
+/** Where a chosen `POSTGRES_PASSWORD` came from. */
+export type PostgresPasswordSource = 'environment' | 'generated' | 'legacy'
+
 export interface PostgresPasswordChoice {
   value: string
-  /** True when the value is the legacy password an existing volume was created with. */
-  legacy: boolean
+  source: PostgresPasswordSource
+}
+
+interface ChooseOptions {
+  /** `POSTGRES_PASSWORD` from the shell, which Compose interpolates over `.env`. */
+  shellValue?: string
+  hasDatabaseVolume?: (project: string) => boolean
 }
 
 /**
- * Picks the `POSTGRES_PASSWORD` a Compose install's `.env` needs, or null when it
- * already has one. The production Compose file requires the variable, so an
- * install that never set it must gain one before Compose will start — and the
- * value must match what the data volume was created with: a fresh password for
- * a new volume, the legacy one for a volume that already exists. Guessing wrong
- * in the other direction would lock the app out of its own database.
+ * Picks the `POSTGRES_PASSWORD` to write to a Compose install's `.env`, or null
+ * when `.env` already has one. The production Compose file requires the
+ * variable, and the value must match what the data volume was created with —
+ * Postgres ignores `POSTGRES_PASSWORD` on an existing data directory, so a
+ * wrong value locks the app out of its own database:
+ *
+ * - A value exported in the shell is what Compose is using, so it is persisted;
+ *   otherwise a later run without the export would fall back to a guess.
+ * - With no value anywhere, an existing volume was created with the legacy
+ *   password, and a project with no volume yet gets a generated one.
  */
 export function choosePostgresPassword(
-  configured: string | undefined,
+  envFileValue: string | undefined,
   project: string,
-  hasDatabaseVolume: (project: string) => boolean = composeDatabaseVolumeExists
+  {
+    shellValue = process.env.POSTGRES_PASSWORD,
+    hasDatabaseVolume = composeDatabaseVolumeExists,
+  }: ChooseOptions = {}
 ): PostgresPasswordChoice | null {
-  if (configured) return null
+  if (envFileValue) return null
+  if (shellValue) return { value: shellValue, source: 'environment' }
   return hasDatabaseVolume(project)
-    ? { value: LEGACY_POSTGRES_PASSWORD, legacy: true }
-    : { value: generateSecret(), legacy: false }
-}
-
-/**
- * The value Compose will interpolate for `POSTGRES_PASSWORD`: the shell
- * environment wins over `.env`, so a value exported there is already in effect.
- */
-export function configuredPostgresPassword(envFileValue: string | undefined): string | undefined {
-  return process.env.POSTGRES_PASSWORD || envFileValue || undefined
+    ? { value: LEGACY_POSTGRES_PASSWORD, source: 'legacy' }
+    : { value: generateSecret(), source: 'generated' }
 }
 
 /** Whether a Compose project already has a Postgres data volume, found by Compose's own labels. */
@@ -107,15 +116,35 @@ function parseProjectName(stdout: string): string | null {
 }
 
 /**
- * Explains why the legacy password was kept and how to rotate it. `compose` is
- * the pinned `docker compose -p … -f …` prefix for this install.
+ * Reports what was written. `compose` is the pinned `docker compose -p … -f …`
+ * prefix for the install, and `user` the effective `POSTGRES_USER`, both used
+ * in the legacy rotation steps.
  */
-export function legacyPostgresPasswordNote(compose: string): string {
-  return [
-    'This database was created with the password "postgres", so .env now sets',
-    'POSTGRES_PASSWORD=postgres to keep it working. The database is not published',
-    'to the host, so only the containers in this stack can reach it. To rotate it:',
-    `  ${compose} exec db psql -U postgres -c "ALTER ROLE postgres PASSWORD '<new password>'"`,
-    '  then set POSTGRES_PASSWORD=<new password> in .env and run: npx sim-setup start',
-  ].join('\n')
+export function reportPostgresPasswordChoice(
+  choice: PostgresPasswordChoice,
+  { compose, user, envPath }: { compose: string; user: string; envPath: string }
+): void {
+  if (choice.source === 'environment') {
+    p.log.step(`Saved POSTGRES_PASSWORD from the shell environment to ${envPath}`)
+    return
+  }
+  if (choice.source === 'generated') {
+    p.log.step(`Generated POSTGRES_PASSWORD in ${envPath}`)
+    return
+  }
+  p.note(
+    [
+      `This database was created with the password "${LEGACY_POSTGRES_PASSWORD}", so ${envPath}`,
+      `now sets POSTGRES_PASSWORD=${LEGACY_POSTGRES_PASSWORD} to keep it working. The database is not`,
+      'published to the host, so only the containers in this stack can reach it. To rotate it:',
+      `  ${compose} exec db psql -U ${user} -c "ALTER ROLE CURRENT_USER PASSWORD '<new password>'"`,
+      '  then set POSTGRES_PASSWORD=<new password> in .env and run: npx sim-setup start',
+    ].join('\n'),
+    'Database password'
+  )
+}
+
+/** The Postgres role Compose initializes, which the shell overrides over `.env` like any variable. */
+export function postgresUser(envFileValue: string | undefined): string {
+  return process.env.POSTGRES_USER || envFileValue || 'postgres'
 }

packages/sim-setup/src/lifecycle.ts

@@ -5,8 +5,8 @@ import { ensureProductionComposeFile } from './compose-asset'
 import {
   choosePostgresPassword,
   composeFileRequiresPostgresPassword,
-  configuredPostgresPassword,
-  legacyPostgresPasswordNote,
+  postgresUser,
+  reportPostgresPasswordChoice,
 } from './compose-database'
 import { legacyComposeProjectName } from './compose-project'
 import { directoryOverride, resolveSetupContextAtRoot, SETUP_CONTEXT } from './context'
@@ -210,20 +210,15 @@ function ensureComposePostgresPassword(install: ComposeInstall): void {
   if (!composeFileRequiresPostgresPassword(install.file)) return
   const envPath = path.join(install.dir, '.env')
   const content = existsSync(envPath) ? readFileSync(envPath, 'utf8') : ''
-  const choice = choosePostgresPassword(
-    configuredPostgresPassword(parseEnv(content).get('POSTGRES_PASSWORD')),
-    install.project
-  )
+  const vars = parseEnv(content)
+  const choice = choosePostgresPassword(vars.get('POSTGRES_PASSWORD'), install.project)
   if (!choice) return
   writeEnvFile(envPath, upsertEnv(content, 'POSTGRES_PASSWORD', choice.value))
-  if (choice.legacy) {
-    p.note(
-      legacyPostgresPasswordNote(`docker compose -p ${install.project} -f ${install.file}`),
-      'Database password'
-    )
-  } else {
-    p.log.step(`Generated POSTGRES_PASSWORD in ${envPath}`)
-  }
+  reportPostgresPasswordChoice(choice, {
+    compose: `docker compose -p ${install.project} -f ${install.file}`,
+    user: postgresUser(vars.get('POSTGRES_USER')),
+    envPath,
+  })
 }
 
 /** Dev mode owns the split env files and, usually, the managed Postgres/Redis. */

packages/sim-setup/src/modes/compose.ts

@@ -7,8 +7,8 @@ import {
   choosePostgresPassword,
   composeFileRequiresPostgresPassword,
   composeProjectName,
-  configuredPostgresPassword,
-  legacyPostgresPasswordNote,
+  postgresUser,
+  reportPostgresPasswordChoice,
 } from '../compose-database'
 import { legacyComposeProjectName, standaloneComposeProjectName } from '../compose-project'
 import { SETUP_CONTEXT } from '../context'
@@ -188,7 +188,7 @@ export async function runComposeMode(detection: Detection, quick: boolean): Prom
   }
   const postgresPassword = composeFileRequiresPostgresPassword(composeFile)
     ? choosePostgresPassword(
-        configuredPostgresPassword(root.vars.get('POSTGRES_PASSWORD')),
+        root.vars.get('POSTGRES_PASSWORD'),
         composeProject ?? composeProjectName(composeFile, ROOT)
       )
     : null
@@ -232,13 +232,12 @@ export async function runComposeMode(detection: Detection, quick: boolean): Prom
   for (const key of Object.keys(values)) remove.delete(key)
   reconcileEnvValues('root', [...remove], values)
   p.log.step('Wrote .env (compose reads it for variable substitution)')
-  if (postgresPassword?.legacy) {
-    p.note(
-      legacyPostgresPasswordNote(composeCommand(composeFile, composeProject)),
-      'Database password'
-    )
-  } else if (postgresPassword) {
-    p.log.step('Generated POSTGRES_PASSWORD')
+  if (postgresPassword) {
+    reportPostgresPasswordChoice(postgresPassword, {
+      compose: composeCommand(composeFile, composeProject),
+      user: postgresUser(root.vars.get('POSTGRES_USER')),
+      envPath: root.path,
+    })
   }
 
   const validation = spawnSync('docker', composeArgs(composeFile, composeProject, 'config'), {