Changing the Database Password

The exact steps depend on your deployment type, and — for native/PM2 — whether encryption at rest is already set up. Pick the right tab below.

Order matters

In every path, update the app's stored credential before changing Postgres's actual password, then restart immediately after the Postgres change. That way the only window where the two are out of sync is the few seconds between the ALTER ROLE/ALTER USER and the restart — not the (potentially much longer) time between editing a config file and remembering to restart.

Native/PM2 — encryptedNative/PM2 — unencryptedDocker

Use this if backend/.env already has a DB_PASSWORD_ENC line (see Secrets & Encryption).

Don't just re-run install-onprem.sh

Re-running the installer reconciles Postgres to whatever password is already encrypted — it doesn't generate or accept a new one. It's the right tool for keeping things in sync during an upgrade, not for rotating the password.

1. Generate a new strong password and encrypt it with the existing master key:

   cd backend
   NEW_PASSWORD=$(head -c 32 /dev/urandom | base64 | tr -dc 'a-zA-Z0-9' | head -c 32)
   node dist/scripts/encrypt-env-value.js encrypt /etc/itsm/env-master.key "$NEW_PASSWORD"
   # copy the printed iv:authTag:ciphertext value
   

2. Replace the DB_PASSWORD_ENC= line in backend/.env with the new ciphertext (keep ENV_MASTER_KEY_FILE unchanged).
3. Apply the same password to the Postgres role:

   sudo -u postgres psql -c "ALTER ROLE itsm_user WITH PASSWORD '${NEW_PASSWORD}';"
   

   (replace itsm_user with your actual DB_USER)
4. Restart immediately:

   pm2 restart itsm-backend
   pm2 logs itsm-backend --lines 50   # confirm a clean startup, no auth errors
   curl -sf http://localhost:3001/api/health
   

5. Clear $NEW_PASSWORD from your shell history / unset it.

Use this if backend/.env still has a plaintext DB_PASSWORD= line. Consider setting up encryption first — it takes one command and this becomes the encrypted flow above.

1. Generate a new strong password.
2. Update DB_PASSWORD= in both .env (root) and backend/.env — install-onprem.sh copies root → backend on every future run, so leaving them out of sync will silently revert the backend's copy on the next upgrade.
3. Apply it to the Postgres role:

   sudo -u postgres psql -c "ALTER ROLE itsm_user WITH PASSWORD 'NewStrongPassword';"
   

4. Restart immediately:

   pm2 restart itsm-backend
   pm2 logs itsm-backend --lines 50
   curl -sf http://localhost:3001/api/health
   

The db container's POSTGRES_PASSWORD only takes effect the first time it initializes an empty volume — editing .env alone does not change an already-running database's password. You have to change both.

1. Generate a new strong password.
2. Change the live Postgres role's password inside the running container:

   docker exec -it itsm-db-prod psql -U ${DB_USER} -c "ALTER USER ${DB_USER} WITH PASSWORD 'NewStrongPassword';"
   

3. Update DB_PASSWORD in .env to the same value.
4. Recreate the backend container so it picks up the new DATABASE_URL (a plain restart reuses the old, already-baked-in environment — it won't see the .env change):

   docker compose -f docker-compose.prod.yml up -d backend
   

5. Verify:

   docker compose -f docker-compose.prod.yml logs --tail=50 backend
   curl -sf http://localhost/api/health
   

After rotating

• If you use encryption at rest, the master key itself never changes during a password rotation — only the encrypted value does.
• Update your password manager / secrets vault entry for this environment.
• If you have an offsite backup of .env from before the rotation, note that restoring it would reintroduce the old password — see Backups & Disaster Recovery.