Introducing a new way to review your PRs.

Read the announcement

immich-app / immich

High performance self-hosted photo and video management solution.

View on GitHub

21 documents · Updated Oct 19, 2026

docs / storage-and-system-operations

Storage and system operations

Storage and system operations provide the shared services that keep the server's files, database state, configuration, and operational state safe and observable. They connect asset paths and disk access to scheduled backups, integrity checks, maintenance mode, telemetry, version checks, and system metadata.

Operational boundary

The operational boundary sits between user-facing features and the server environment. Asset and maintenance flows use it to reach files and durable state without each feature defining its own storage rules. The broader job model that schedules these services is described in Background jobs and operations.

Storage access

The storage layer gives the server one place to read, write, move, stream, scan, watch, and measure files. server/…/storage.repository.ts provides the file-system boundary, while server/…/storage.core.ts gives product features stable locations for originals, derived media, user libraries, thumbnails, encoded video, backups, and temporary operational data.

The server selects a media location during startup and checks that its managed folders can be read and written. It records the selected location so a change can be detected and file paths can be migrated in a controlled way. File moves update the matching database path only after the new file passes size checks and, when enabled, checksum checks. This keeps database references and files aligned when assets or derived files move.

The same boundary reports disk capacity for server status and supports streamed file work. These capabilities let maintenance and media services handle large files without duplicating path rules or direct file-system access.

References: server/…/storage.service.ts• L21-134 server/…/storage.core.ts• L96-159 server/…/storage.core.ts• L198-314 server/…/storage.repository.ts• L49-55 server/…/storage.repository.ts• L215-299 server/…/server.service.ts• L67-81

Storage templates

Storage templates define the library path for an asset from its date, name, type, camera data, and optional album data. An administrator can enable a template and choose a pattern from the supported token and preset set. The template service validates the pattern before use and compiles it when configuration starts or changes.

When metadata becomes available, the service queues a migration for the asset. A full migration can move the original and its sidecar, keep live-photo parts together, avoid external assets, resolve duplicate names, and remove empty folders. The move is protected by a database lock and the generated path must remain inside the owner's library root.

See Data model and persistence for the durable asset records that store these paths.

References: server/…/storage-template.service.ts• L25-57 server/…/storage-template.service.ts• L92-136 server/…/storage-template.service.ts• L138-225 server/…/storage-template.service.ts• L227-265 server/…/storage-template.service.ts• L268-395 server/…/config.dto.ts• L328-334

Configuration and durable system state

Configuration controls the policy of operational services. Durable system metadata stores small pieces of state that must survive restarts but do not belong to a main domain record. Together they let services apply policy at startup, react to changes, and resume long work.

Configuration views

The configuration service builds one validated system configuration from defaults and either a YAML file or a partial value stored in system metadata. It exposes filtered views for administrators, signed-in users, and public clients. This prevents a client from receiving settings outside its visibility while keeping all services on the same source of truth.

At bootstrap, the service publishes the effective configuration so dependent services can apply their initial state. An administrator update is validated before it is saved, then publishes a configuration event that re-applies live logging and machine-learning settings and clears the configuration cache. An environment-selected configuration file makes the system read-only through the admin update API, and an environment log-level setting takes precedence over the matching stored setting. The service also tears down machine-learning state during application shutdown.

References: server/…/config.ts• L18-63 server/…/config.ts• L65-136 server/…/system-config.service.ts• L20-109 server/…/config-admin.controller.ts• L14-45 server/…/config-user.controller.ts• L14-34 server/…/config-public.controller.ts• L14-34

System metadata

System metadata is a keyed set of JSON values in the database. It holds operational state such as onboarding, media-location checks, maintenance mode, release-check results, integrity checkpoints, license data, and the saved configuration when no external configuration file is active.

Services use typed keys to read and replace each value. This keeps state small and separate from user and asset records. The metadata service exposes selected states to administrators, while internal services use the same store to coordinate startup checks and resumable work.

References: server/…/system-metadata.table.ts• L1-12 server/…/system-metadata.repository.ts• L12-45 server/…/system-metadata.service.ts• L11-32 server/…/system-metadata.controller.ts• L13-61 server/…/storage.service.ts• L50-134 server/…/integrity.service.ts• L533-603

Database safety services

Database safety services protect the relationship between the database and the file library. Backups protect database state for recovery, while integrity checks find file state that no longer matches database state.

Database backups

Database backups run on a configured schedule and are stored in the managed backups folder. The service creates a PostgreSQL dump, compresses it, and renames a temporary file only after the stream completes. It lists, uploads, downloads, and deletes valid backup files, then removes old routine backups according to the retention limit.

Restore is a maintenance operation rather than a normal request. It first creates a restore point, loads a supported backup into PostgreSQL, runs migrations, checks that an administrator exists, and checks that the API can start. If the post-restore checks fail, it restores the restore point and reports the failure to the maintenance client.

The restore flow is exposed to administrators through the database-backup API and to the restricted maintenance worker. This split allows recovery when the normal application is not configured or cannot serve its usual routes.

References: server/…/database-backup.service.ts• L55-105 server/…/database-backup.service.ts• L227-359 server/…/database-backup.service.ts• L361-470 server/…/database-backup.controller.ts• L21-101 server/…/database-backups.ts• L1-24

Integrity checks

Integrity checks compare files on disk with paths and checksums recorded in the database. They cover three distinct conditions: untracked files, missing files, and checksum failures. Each condition runs on its own schedule and writes a report that an administrator can inspect, export, download, or resolve.

The checks run in batches so large libraries do not require one long request. A checksum pass stores a checkpoint and stops at its time or coverage limit, then resumes from that point later. Report actions are tied to the kind of mismatch: an asset may move to trash, a derived file may be removed from tracking, or an untracked file may be deleted only when no tracked record uses its path.

The integrity API is described in Automated asset analysis only where it intersects with background work; its purpose here is operational repair of storage state.

The following diagram shows how a scheduled integrity pass turns file and database observations into reports or safe cleanup actions.

flowchart LR
    S[Scheduled integrity job] --> T{Check type}
    T --> U[Scan disk for untracked files]
    T --> M[Check database paths for missing files]
    T --> C[Hash recorded files]
    U --> R[Integrity report]
    M --> R
    C --> R
    R --> A[Admin review]
    A --> X[Trash asset]
    A --> D[Remove derived or untracked file]

References: server/…/integrity.service.ts• L64-137 server/…/integrity.service.ts• L139-199 server/…/integrity.service.ts• L220-315 server/…/integrity.service.ts• L372-435 server/…/integrity.service.ts• L488-603 server/…/integrity-admin.controller.ts• L19-93

Observability and release state

Operational services expose state that helps an operator understand server health and change over time. Telemetry measures runtime activity, while version services track the running release and check for newer releases.

Telemetry metrics

Telemetry publishes Prometheus metrics through OpenTelemetry when the matching metric groups are enabled. Automatic instrumentation covers HTTP, queues, NestJS activity, and PostgreSQL. Event handlers add product metrics for user totals, queue activity, and job outcomes.

Repository methods can also be wrapped to record duration. The metric groups are independently enabled for API, host, jobs, and repository activity, so an installation can choose the level of operational detail it needs.

References: server/…/telemetry.repository.ts• L22-50 server/…/telemetry.repository.ts• L53-104 server/…/telemetry.repository.ts• L106-185 server/…/telemetry.service.ts• L7-61

Version state

The version service reports the running server version, records each newly observed version in upgrade history, and checks a configured release channel for a newer version. The check runs as a background task and saves its last result in system metadata so clients can receive a consistent notification after reconnecting.

Version history supports an audit of upgrades. A version change can also trigger compatibility work that belongs to the wider background-job system. The command-line version command provides the current server version without requiring the web API.

References: server/…/version.service.ts• L38-87 server/…/version.service.ts• L89-164 server/…/version-history.repository.ts• L8-24 server/…/version-history.table.ts• L1-13 server/…/version.command.ts• L1-23

Maintenance mode

Maintenance mode creates a restricted operating state for work that must not run beside normal user traffic. It is used most visibly for database restore, but it also provides a safe place to inspect an existing installation and recover access when the normal application is unavailable.

Maintenance lifecycle

The normal maintenance service stores a signed, short-lived access secret and requests an application restart. The maintenance worker then serves only the maintenance surface, authenticates its routes with a maintenance token, reports progress over a WebSocket, and can list, upload, download, or delete database backups.

The restore action runs under a database lock. After a successful restore and health check, the worker clears the maintenance state and restarts the application. A failed action remains visible as an error in the maintenance status instead of silently returning the server to normal service.

The maintenance page in the web client consumes this status to guide installation detection, backup selection, restore progress, and completion. The surrounding job and worker model is covered by Background jobs and operations.

References: server/…/maintenance.service.ts• L21-91 server/…/maintenance-worker.service.ts• L39-87 server/…/maintenance-worker.service.ts• L242-360 server/…/maintenance-worker.controller.ts• L38-138 server/…/maintenance-websocket.repository.ts• L15-95 server/…/maintenance-health.repository.ts• L7-53 web/…/MaintenanceRestoreFlow.svelte• L1-200

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep storage-folder names, path builders, mount checks, and database path fields aligned. A mismatch can make valid files look missing or place new files outside the intended library.
  • Keep storage-template tokens, validation, migration jobs, and live-photo path handling aligned. A new token or path rule must work for both single-asset and full migrations.
  • Keep backup naming rules aligned between creation, listing, retention, download, upload, and restore. A name accepted by one step but rejected by another can make a backup unusable.
  • Keep configuration visibility maps aligned with the admin, user, and public endpoints. A field can be silently hidden or exposed if its schema visibility is not updated with the route contract.
  • Keep configuration bootstrap, update, cache invalidation, and shutdown behavior aligned with the services that apply logging and machine-learning state. A change to one lifecycle event can leave live state different from the saved configuration.
  • Keep system-metadata keys aligned with the state readers and writers. Changing a stored shape affects startup checks, resumable integrity work, restore state, and client status responses.
  • Keep maintenance status actions and task names aligned across the worker, WebSocket events, restore callbacks, and web maintenance flow.

Important failure modes

TriggerConsequenceGuard
A managed storage folder cannot be read or written at startupThe server refuses to start, or storage checks are ignored only when the configured override allows itMount files and read/write checks run before normal storage use; the override is explicit in environment configuration
The selected media location differs from the saved location and an asset path does not start under the saved rootStartup stops instead of migrating paths that may point to unrelated filesThe media-location lock checks a sample path before path migration
A storage-template destination already contains the same nameThe migration could overwrite or lose the original asset nameThe destination gets a numbered suffix and the move records and verifies the file transition
A database dump or restore process failsA partial backup is not treated as valid; a failed restore can leave the database in an unsafe stateBackups use temporary files; restore creates a restore point and rolls back after migration or health-check failure
A file is missing, untracked, or has a different checksumThe database and file library can disagree about the assetScheduled integrity reports separate the mismatch type and require an administrator action for cleanup
A checksum run reaches its time or percentage limitThe full library is not checked in one runThe last processed date is stored and the next run resumes from the checkpoint
A configuration file is active while an administrator tries to save settingsThe update is rejected and the file remains the source of truthThe configuration service blocks admin updates when the file setting is present
An environment log-level setting is active while an administrator changes logging settingsThe configuration update is rejected, so stored logging values do not override the environment policyConfiguration validation compares the logging section before the update and treats the environment value as authoritative
Maintenance restore passes SQL loading but fails migrations or API healthThe restored system may not be safe to exposeRestore runs migrations, checks for an administrator, checks API startup, and restores the restore point on failure

Key files

FileWhy to read it
server/…/storage.core.tsShows the shared path model and the rules that keep file moves linked to database paths.
server/…/storage.service.tsShows startup media-location selection, mount checks, and file deletion work.
server/…/storage-template.service.tsShows how administrator templates become asset migrations.
server/…/database-backup.service.tsShows scheduled backup, retention, upload, restore, rollback, and health-check behavior.
server/…/integrity.service.tsShows the three storage integrity checks and the repair actions behind their reports.
server/…/config.tsShows how defaults, file configuration, saved partial configuration, validation, and caching combine.
server/…/system-config.service.tsShows configuration visibility, startup and shutdown handling, and the events that refresh live services.
server/…/system-metadata.repository.tsShows the durable key-value boundary used for operational state.
server/…/telemetry.repository.tsShows metric groups, Prometheus export, automatic instrumentation, and repository timing.
server/…/version.service.tsShows version history, release checks, and client release notifications.
server/…/maintenance-worker.service.tsShows the restricted runtime used for restore and other maintenance actions.
server/…/maintenance-worker.controller.tsShows the maintenance-only API surface available while normal routes are unavailable.
web/…/MaintenanceRestoreFlow.svelteShows how the client moves from installation detection to backup selection.