mirror of
https://github.com/Studio-Saelix/sencho.git
synced 2026-07-26 20:00:08 +00:00
Anso
c6d1631afe
* feat(recovery): add safe-mode recovery surface and emergency CLI Add a read-only Recovery tab under Settings (admin-only) backed by a new GET /api/diagnostics endpoint reporting app version, database integrity, encryption-key status, Docker reachability, account and SSO counts, and non-secret configuration. The endpoint loads without Docker or live metrics so it stays available when the dashboard does not, requires a genuine admin session, and builds its config block from a non-secret allowlist so no credentials are ever exposed. Expand the emergency command-line toolkit beyond the two-factor reset with seven host-level commands: reset-password, create-emergency-admin, clear-sessions, disable-sso, diagnostics, validate-db, and backup-data. Each prints its result, exits with a meaningful status code, and writes an audit entry where it changes state. Document the toolkit in a new operator guide and link it from the recovery and two-factor pages. * feat(recovery): download the emergency command reference as a text file The recovery commands are needed exactly when the dashboard is unreachable, so reading them only in-app is a chicken-and-egg problem. Add a Download button to the command-line section that saves the full `docker compose exec sencho ...` reference as a text file, letting operators keep it on hand before they need it. Reuses a shared download helper with the existing diagnostics export. * fix(recovery): harden diagnostics, backup, and emergency-admin against edge cases Address findings from an independent review of the recovery toolkit: - DiagnosticsService now degrades instead of throwing when a queried table is missing or corrupt: each read falls back and is folded into database.ok, so a broken database reports "problem detected" rather than failing the whole endpoint or showing a misleading healthy state with zeroed counts. - backup-data refuses a destination that resolves to the live database, which would otherwise report success while producing no separate copy. - create-emergency-admin now applies the same username rule as the user- management route, extracted to a shared helper so both stay in sync. Adds tests for a missing read table, a malformed emergency-admin username, and the backup same-target rejection.
111 lines
4.9 KiB
Plaintext
111 lines
4.9 KiB
Plaintext
---
|
|
title: Emergency command-line recovery
|
|
description: Host-level commands that recover access when the Sencho UI is unreachable, plus the in-app Recovery surface for everyday health checks.
|
|
---
|
|
|
|
When the dashboard is unreachable, an identity provider blocks the login screen, or every administrator is locked out, Sencho ships a set of emergency commands you run from a shell on the host. Each one acts on the same SQLite database the application uses (it respects the container's `DATA_DIR`), and each writes an audit-log entry attributed to `cli` where it changes state, so the action is traceable afterwards.
|
|
|
|
All commands run through the Sencho container:
|
|
|
|
```bash
|
|
docker compose exec sencho node dist/cli/<command>.js [arguments]
|
|
```
|
|
|
|
Each command prints what it did and exits with code `0` on success or non-zero on failure, so it can gate a script.
|
|
|
|
<Note>
|
|
Before you rely on Sencho in earnest, back up `DATA_DIR` and `COMPOSE_DIR`. The [Recovery guide](/operations/recovery) explains why most recovery is file-level, and [Backup & Restore](/operations/backup) gives a copy-and-restore routine.
|
|
</Note>
|
|
|
|
## In-app Recovery surface
|
|
|
|
For everyday checks you do not need a shell. An administrator can open **Settings · Recovery** for a read-only health snapshot: app version, database integrity, encryption-key status, Docker reachability, administrator and two-factor counts, and the non-secret configuration. The page loads without Docker or live metrics, so it stays available when the rest of the dashboard does not. From there you can export the snapshot as JSON, reset this browser's interface preferences to defaults, and see the same command reference printed below.
|
|
|
|
The command line is the fallback for when even that surface cannot be reached.
|
|
|
|
## Sign-in and account recovery
|
|
|
|
### Reset a forgotten password
|
|
|
|
Resets a local user's password and signs out their existing sessions.
|
|
|
|
```bash
|
|
docker compose exec sencho node dist/cli/resetPassword.js <username> <new-password>
|
|
```
|
|
|
|
Applies to local accounts only. Users who sign in through SSO are managed by their identity provider.
|
|
|
|
### Create an emergency administrator
|
|
|
|
Creates a fresh local administrator when every existing admin is locked out but the database is otherwise intact, so you avoid discarding configuration with a full setup reset.
|
|
|
|
```bash
|
|
docker compose exec sencho node dist/cli/createEmergencyAdmin.js <username> <password>
|
|
```
|
|
|
|
It refuses to overwrite an existing user; use the password reset above for an account that already exists. Sign in afterwards and review your other accounts.
|
|
|
|
### Clear the existing two-factor enrolment
|
|
|
|
Removes a user's second factor so they can sign in with their password alone and re-enrol.
|
|
|
|
```bash
|
|
docker compose exec sencho node dist/cli/resetMfa.js <username>
|
|
```
|
|
|
|
See [Managing Two-Factor Authentication](/operations/two-factor-admin) for the full two-factor workflow, including the in-app reset another admin can perform without a shell.
|
|
|
|
### Sign every user out
|
|
|
|
Invalidates every active session at once, for example after a suspected stolen session cookie.
|
|
|
|
```bash
|
|
docker compose exec sencho node dist/cli/clearSessions.js
|
|
```
|
|
|
|
Everyone signs in again on their next request; nothing else changes.
|
|
|
|
### Disable a broken single sign-on provider
|
|
|
|
Re-enables local password sign-in when a misconfigured identity provider blocks the login screen.
|
|
|
|
```bash
|
|
docker compose exec sencho node dist/cli/disableSso.js [provider]
|
|
```
|
|
|
|
With no argument it disables every enabled provider. The stored configuration is preserved (only the enabled flag is cleared), so you can correct it and turn it back on from **Settings · SSO**.
|
|
|
|
## Inspecting and protecting your data
|
|
|
|
### Print a diagnostic summary
|
|
|
|
Prints the same snapshot the in-app Recovery surface shows, as JSON. Read-only and free of secrets, so it is safe to paste into a bug report.
|
|
|
|
```bash
|
|
docker compose exec sencho node dist/cli/diagnostics.js
|
|
```
|
|
|
|
### Validate the database and encryption key
|
|
|
|
Runs a database integrity check, confirms the core tables exist, confirms the encryption key is present and usable, and confirms at least one administrator exists. Exits non-zero if any check fails.
|
|
|
|
```bash
|
|
docker compose exec sencho node dist/cli/validateDb.js
|
|
```
|
|
|
|
Use this to decide whether a restore is needed before you start the application against a questionable data directory.
|
|
|
|
### Back up the data directory
|
|
|
|
Writes a consistent copy of `sencho.db` (using SQLite's online backup, safe while Sencho is running) and `encryption.key` to a target directory.
|
|
|
|
```bash
|
|
docker compose exec sencho node dist/cli/backupData.js [destination-dir]
|
|
```
|
|
|
|
With no argument it writes a timestamped folder under `DATA_DIR/backups`. The copy contains your encryption key, so store it as carefully as the original.
|
|
|
|
<Warning>
|
|
These commands act directly on live data. Read the description of each before running it, and prefer the least disruptive option that solves your problem. None of them touches your Docker stacks or their compose files; those are independent of Sencho.
|
|
</Warning>
|