[Feature] Low-resource upload mode: automatically pause processing during uploads

[Tusker86]

The feature

Add an optional low-resource upload mode for small, HDD-backed, or CPU/RAM-constrained Immich servers.

When normal asset uploads are active, Immich should temporarily pause ordinary processing queues, then automatically resume them after a configurable idle delay. The intent is to stop upload writes from competing with thumbnails, metadata extraction, transcodes, OCR, face detection, and similar work on the same disk.

Suggested settings:

• Enable/disable low-resource upload mode.
• Maximum simultaneous asset uploads (for example, 1).
• Idle delay before processing resumes (for example, 5 seconds).
• Explicit protection for system-maintenance queues, so they are never accidentally left paused.
• Clear status logs, such as IMMICH UPLOAD: <user> — upload started and upload finished.

This must work with the normal web uploader and normal mobile backup, without a separate import tool or a manual pause/resume workflow.

Why this is useful

On small servers with HDD storage, a new upload can trigger multiple disk-heavy jobs immediately. Even if each job queue has low concurrency, several different queues can still run at once and compete with the upload. That makes ordinary browser uploads and phone backups slow or unreliable.

My proof-of-concept

I tested this by adding a server-side hook to Immich's normal asset-upload interceptor. It:

1. serializes asset uploads with one shared promise-based gate;
2. pauses only queues that were not already paused when the first upload arrives;
3. deliberately excludes the maintenance/background queue;
4. releases the next upload only when the preceding upload handler finishes;
5. retains the list of queues it paused through a five-second idle window; and
6. resumes exactly those queues after the final upload is idle for five seconds.

This worked for both browser uploads and mobile backups because both use the normal asset-upload endpoint. The browser may still show several files waiting, but only one request reaches the server upload handler at a time.

This is currently an unsupported, version-specific custom patch to compiled server code. A supported configuration would be safer, easier to maintain through upgrades, and useful for Raspberry Pi, NAS, USB-HDD, and other low-resource installations.

I found a related discussion about the web uploader defaulting to two concurrent uploads: #15307. This proposal is broader: it is a server-side, upload-aware mode that prevents background processing from competing with uploads.

Core implementation

This is the central JavaScript used in the server upload interceptor (imports and QueueService injection are required in the matching Immich version):

let immichUploadPauseActive = 0;
let immichUploadPauseTimer;
let immichUploadPausedQueues = [];
let immichUploadGate = Promise.resolve();

async uploadPauseBegin() {
  immichUploadPauseActive++;
  if (immichUploadPauseTimer) clearTimeout(immichUploadPauseTimer);
  if (immichUploadPauseActive > 1 || immichUploadPausedQueues.length) return;

  for (const queue of await this.queueService.getAll()) {
    if (queue.name !== QueueName.BackgroundTask && !queue.isPaused) {
      await this.queueService.update(undefined, queue.name, { isPaused: true });
      immichUploadPausedQueues.push(queue.name);
    }
  }
}

uploadPauseEnd() {
  immichUploadPauseActive = Math.max(0, immichUploadPauseActive - 1);
  if (!immichUploadPauseActive) {
    immichUploadPauseTimer = setTimeout(() => void this.uploadPauseResume(), 5000);
  }
}

async uploadPauseResume() {
  if (immichUploadPauseActive) return;
  for (const name of immichUploadPausedQueues.splice(0)) {
    await this.queueService.update(undefined, name, { isPaused: false });
  }
}

// At the start of an asset upload:
await this.uploadPauseBegin();
const previousUpload = immichUploadGate;
immichUploadGate = new Promise((resolve) => { releaseUploadGate = resolve; });
await previousUpload;

// In the request-finalization handler:
releaseUploadGate?.();
this.uploadPauseEnd();

The complete version must retain Immich's normal Multer handler and use an RxJS finalize() callback so the gate is released on both success and error. Do not pause BackgroundTask: it contains maintenance work such as deletion and cleanup. This is a compiled-code patch, so it needs rechecking after every Immich update.

[bo0tzz]

#14329