Use the interactive recovery command when a self-hosted deployment is locked
out because password sign-in is disabled, a user’s password is unknown, or the
user was removed from the workspace IAM policy.
Stop every Bytebase server connected to the metadata database before recovery.
Restart all servers after recovery so they reload the updated settings and IAM
policy.
Before recovery
- Back up the metadata database.
- Stop every Bytebase server instance or replica.
- Use the same Bytebase version and metadata connection configuration as the
stopped deployment. Follow Deploy with Docker
for embedded data and port configuration, or Configure External
PostgreSQL for
PG_URL.
Recovery requires an interactive terminal and a metadata database containing
exactly one workspace, which must be active.
Run recovery
For embedded PostgreSQL, pass the deployment’s --data and any custom --port.
For external PostgreSQL, provide the deployment’s PG_URL and credentials.
The command displays:
Enable password sign-in
Use this action when an existing administrator password is known but password
sign-in is disabled. The command verifies that a usable administrator identity
exists, then turns off Disallow password sign-in.
Reset user password
Use this action for any existing, active end user. The user does not need to be
an administrator.
The command displays the workspace password requirements before accepting the
new password. If the user is not a workspace member, it can add one existing
role after confirmation. If password sign-in is disabled, run Enable password
sign-in in the same session.
Recovery does not create or reactivate users, create or edit roles, clear MFA,
revoke tokens, or repair an identity provider.
After recovery
- Exit recovery and restart every Bytebase server.
- Sign in through
/auth and verify the recovered account’s access.
- Repair and test the identity provider.
- Re-enable Disallow password sign-in if it was enabled before the outage.
- Review the warning-level recovery audit events.
