How do we reset Chef Habitat Builder Depot Postgres DB password?

How to we rotate the password for Chef Habitat Builder with external Postgres DB ?

This is for externally postgres DB for Chef Habitat on Prem builder

• Chef Habitat On-Prem Builder Depot
• PostgreSQL hosted on a separate external server

OverView

This article describes the procedure for resetting or rotating the PostgreSQL database password used by the Chef Habitat On-Prem Builder Depot environment when the database is hosted externally.

Use this procedure in the following scenarios:

• The database password has expired, or must be replaced.
• Password rotation is required to meet security or compliance requirements.
• Builder services or applications are experiencing PostgreSQL authentication failures due to an invalid or expired password.

This runbook provides the steps required to safely update the PostgreSQL password and ensure the Habitat Builder Depot services continue to connect successfully after the password change.

 

Prerequisites

• Validate the existing password for the postgres username and password.
• Access to the external PostgreSQL server with permission to change the Builder DB user password.
• SSH access to Habitat Builder Depot server & Sudo/admin access on Builder host(s).
• Access to the on-prem-builder directory containing bldr.env and install.sh.
• Approved maintenance window.

 

Resolution

Step 1: Rotate/Change the PostgreSQL user password on the external DB host

Connect to the server hosting the PostgreSQL database.

Switch to the PostgreSQL User

Update the password for the database user used by Builder.

ALTER USER postgres WITH PASSWORD 'NewStrongPassword';

If your Hab Builder deployment uses postgres as the DB user, replace <builder_db_user> accordingly.

Replace NewStrongPassword with a secure password that meets your organization's password policy.

Exit PostgreSQL

 

Step 2: Update Builder deployment configuration

On the Builder host, update the password in bldr.env (within the on-prem-builder directory).

On the Builder host, open the bldr.env file in the on-prem-builder directory and update the database password value.

Habitat Builder Depot stores the PostgreSQL password in a configuration file, update it with the new password.

Confirm related values:

• • • Database host
    • Database port
    • Database username
    • Database name

Sample part of the bldr env file regarding the postgresql config is as below - 

# Only enable and set these if you are using externally hosted PostgreSQL(RDS, Azure Database for PostgreSql etc).
# set PG_EXT_ENABLED = true, uncomment PG_USER and update PG_PASSWORD and POSTGRES_HOST appropriately.
# Migrations from local PostgreSQL to RDS are currently not supported.
export PG_EXT_ENABLED=true
export PG_USER=postgres
export PG_PASSWORD=NewStrongPassword

# The endpoint and port for your Postgresql(local, RDS, Azure Database for PostgreSql etc)
# Change only if needed 
export POSTGRES_HOST=Host of Posgresql or RDS database server
export POSTGRES_PORT=5432

If any  values of the external Postgresql DB is not present, add the required values accordingly.

Please refer the full bldr.env.sample sample env file is located in the location - https://github.com/habitat-sh/on-prem-builder/blob/main/bldr.env.sample

Step 3: Re-apply deployment configuration

From the same on-prem-builder directory, with the bldr.env file updated with latest values, run:

./install.sh

This reapplies configuration and updates service environment values.

Running the install script does make only the required changes. It doesnt reinstall the complete application.

 

Step 4: Restart Habitat services

Restart the Habitat Builder Depot application or related services to ensure the new credentials are loaded.

sudo systemctl restart hab-sup

 

Step 5: Validate service health

Monitor Builder services and logs to confirm successful startup and database connectivity.

Validation

• The application starts successfully and all the services are up and running. 

  hab svc status

• Builder API and related services are running normally.
• No PostgreSQL authentication failures in logs.
• Builder UI/API operations that require DB access succeed.
• Optional manual DB login test with new password succeeds.

 

Rollback

• Restore the previous known-good password on PostgreSQL.
• Revert bldr.env to previous value.
• Run ./install.sh again.
• Restart services and validate.

 

Troubleshooting

Authentication still fails

• • Confirm the correct DB user was updated.
  • Re-check bldr.env for typos or special character handling issues.
  • Re-run install.sh and restart services.
  • Confirm the external PostgreSQL host/port in bldr.env is correct.

Changes do not persist

You can locate current runtime DB settings but changes do not persist

• • • Ensure update was made in bldr.env, not only runtime-generated service config.
    • Ensure changes were made in bldr.env, not in /hab/svc/builder-api/config/config.toml.

DB admin access is unavailable

• • Follow PostgreSQL admin recovery process during a controlled maintenance window.
  • Revert any temporary authentication relaxations immediately after reset.

 

Security Notes

• Use strong, unique passwords.
• Prefer a dedicated least-privilege DB account for Builder.
• Store secrets in an approved secrets manager.
• Track rotation date, approver, and change ticket for audit.

 

Best Practices

• Use a strong, unique password.
• Use a dedicated, least-privilege DB account for Builder.
• Store credentials securely using a secrets management solution whenever possible.
• Avoid hardcoding passwords in application source code.
• Rotate database passwords periodically according to your organization's security policy.

 

References 

Chef Habitat On-prem builder - https://docs.chef.io/habitat/builder/on_prem/

bldr.env sample file - https://github.com/habitat-sh/on-prem-builder/blob/main/bldr.env.sample