immich-doctor is a modular maintenance and repair toolkit for Immich installations. The project starts as a safe, CLI-first validation tool and is intentionally designed so that a later API or Web UI can orchestrate the same underlying services.
Why this project exists
Immich users and self-hosters often need more than a simple health check when their instance grows:
- storage layouts need verification
- backup targets need validation before changes happen
- database connectivity needs to be checked during maintenance windows
- future repair workflows need reports, traceability, and operational guardrails
The goal of this repository is to provide a future-proof foundation for backup, analysis, repair, healthcheck, and automation workflows without mixing business logic into one-off CLI scripts.
Current status
Project phase: validation + backup snapshot foundation + repair safety foundation + GUI safety visibility + minimal restore/undo orchestration
Current MVP scope:
- safe hierarchical CLI commands only
- configuration loading from environment or
.env - runtime environment validation
- physical source and derivative file integrity inspection
- metadata extraction failure diagnostics with root-cause classification
- persisted repair-run and repair-journal foundation for later reversible repair flows
- drift-protected plan tokens for inspect -> plan -> apply binding
- quarantine index foundation for later quarantine-first file handling
- persisted backup snapshot records with manifest metadata and explicit files-only vs paired coverage modeling
- pre-repair snapshot creation for integrated mutating repair flows
- GUI visibility for repair runs, journal entries, backup snapshots, and quarantine foundation
- targeted undo for journal-backed runtime permission repairs
- structured full-restore simulation with restore readiness and blockers
- storage path validation
- storage permission validation
- file backup execution through a thin backup application flow
- backup target validation
- non-blocking backup size estimation with persisted background job state
- explicit manual backup target configuration for local, SSH, rsync, and SMB planning
- target validation state and manual backup execution state in the API/UI
- tiered backup execution reporting with explicit verification level
- minimal API health endpoint for the dashboard
- database health validation
- database index inspection
- category-based consistency validation and repair for the supported current PostgreSQL schema
- remote-sync diagnostics with server-side PostgreSQL album/asset link checks
- validation of required external tools when configured
- structured text or JSON reports
Not in scope yet:
- no destructive cleanup phase
- no quarantine moves yet
- no DB backup
- no metadata backup
- no productive SMB backup execution
- no password-based SSH execution support
- no aggressive parallel rsync default
- no automated retention deletion
- no broad full restore execution yet
- no backup-all orchestration
Safety warning
This repository is not production-safe yet.
Do not treat the current scaffold as a proven one-click rollback tool. The current phase adds targeted undo for journal-backed runtime permission repairs and deterministic full-restore simulation, but it still does not provide broad automated restore execution across all repair domains.
Development philosophy
- backup first
- analyze before repair
- quarantine before delete
- dry-run before apply
- no automatic destructive repair in the MVP
- integrated mutating repairs must prepare a real pre-repair snapshot before apply
- future repair actions must be traceable through reports and journals
Planned modules
- backup
- analyze
- repair
- healthcheck
- automations
- future API orchestration layer
- future Web UI orchestration layer
Link Github: https://github.com/vitalyruhl/immich-doctor
