Recover Deployment Credentials#

Use this guide when initialization reports an incomplete or empty credential set, or when interrupted credential generation leaves files that prevent a rerun. Work from the deployment directory as the user who owns its files.

Step 1: Stop Services and Inspect the Files#

If services are running, stop them before changing credential files:

docker compose down

Stop any other running initializers, then inspect the paths listed in Credential Files for missing or empty files and the path or permission problems reported by the initializer. Do not print credential contents in terminal output or logs.

Step 2: Restore or Regenerate the Complete Set#

Choose a path based on whether any service has used these credentials to initialize its accounts.

Option A: Recover Credentials Already Used by Services#

Use this path if any service has initialized its accounts with these credentials, even if the deployment is currently stopped. Do not regenerate the credentials.

  1. Locate a protected backup containing the complete, matching credential set. If no backup is available, stop here and recover the original credentials before proceeding.

  2. Restore all three credential files from that backup. Preserve deployment-specific settings in .env and owner-only permissions (0600) on the restored files.

Option B: Discard Credentials Not Yet Used by Services#

Use this path only if no service has initialized its accounts with these credentials.

Remove all remaining credential files listed in Credential Files. Leave all three destinations absent so that rerunning initialization in Step 4 generates a complete fresh set.

Warning

Do not use this procedure to rotate secrets. Deleting and regenerating credential files does not change the credentials stored by existing services; the new values will fail to authenticate against those services. If you discard the original credentials without a backup, you can be locked out.

Step 3: Remove Abandoned Temporary Files (Optional)#

List hidden files in the deployment directory and its secrets/ directory without displaying their contents:

ls -la . secrets

Look for these temporary-file names, where <token> is a randomly generated string of 32 hexadecimal characters:

  • ..env.<token>.tmp

  • secrets/.postgres-passwd.env.<token>.tmp

  • secrets/.<deployment-slug>-minio-accounts.env.<token>.tmp

If any of these files remain:

  1. Inspect them and confirm which files belong to an abandoned initialization attempt. Do not identify files for deletion solely by their names.

  2. Remove only the confirmed abandoned temporary files.

Step 4: Rerun Initialization#

Rerun init-deployment.sh with the branch and configuration flags used for the deployment. For an existing deployment, follow Update Your Deployment; for a new deployment, resume Prepare Your Deployment. Restart services only after initialization succeeds.