docs(guide): add a low-resource deployment guide in 21 languages (#548)

New guide/low-resource page: what runs well on 2 GB machines, a Raspberry Pi / old laptop Compose walkthrough with tuned caps, the env-var knobs that matter on small hardware, and what to skip. Linked from getting-started, the deployment hardware section, and the sidebar. Translated into all 20 non-English locales via the i18n batch pipeline; parity check and VitePress build pass. Admin merge: docs-only PR, the path-filtered required integration contexts never report (#420 precedent). Closes #497
2026-08-03 07:46:42 +02:00 · 2026-07-17 00:40:48 +08:00
parent 1f4878ac4d
commit fe85dd2b98
104 changed files with 2323 additions and 80 deletions
@@ -1,7 +1,7 @@
 ---
 description: "Distribuisci SnapOtter in produzione con Docker. Requisiti hardware, configurazione GPU e configurazioni di reverse proxy per Nginx, Traefik e Cloudflare."
 i18n_output_hash: 28e72d02cd08
-i18n_source_hash: e0d8d5f6fc87
+i18n_source_hash: 98172965118b
 i18n_provenance: human
 ---

@@ -218,6 +218,8 @@ docker logs SnapOtter 2>&1 | head -20

 Questi valori provengono da benchmark eseguiti su una gamma di sistemi, da una moderna workstation amd64 con una NVIDIA RTX 4070 fino a un Raspberry Pi, eseguendo l'intero catalogo di strumenti su ciascuno e variando i limiti di risorse Docker per trovare il vero limite minimo.

+Ti trovi all'estremità bassa di questi livelli (un Pi, un vecchio laptop, un VPS da 2 GB)? [Configurazioni a basse risorse](/it/guide/low-resource) trasforma questi numeri in una guida concreta con tetti già calibrati.
+
 ### Riferimento rapido {#quick-reference}

 | Livello | Caso d'uso | CPU | RAM | GPU | Archiviazione |
@@ -1,7 +1,7 @@
 ---
 description: "Installa SnapOtter con Docker in un solo comando. Include la configurazione di Docker Compose, la compilazione dal codice sorgente e una panoramica completa delle funzionalità."
 i18n_output_hash: 193499a11aa6
-i18n_source_hash: 24724b5595b2
+i18n_source_hash: 68bf7f60b68d
 i18n_provenance: human
 ---

@@ -19,6 +19,8 @@ docker run -d --name SnapOtter -p 1349:1349 -v SnapOtter-data:/data snapotter/sn

 Questo singolo container esegue tutto ciò di cui ha bisogno: senza alcun `DATABASE_URL` impostato, avvia il proprio PostgreSQL e Redis sull'interfaccia loopback (modalità integrata) e conserva tutti i dati nel volume `SnapOtter-data`. È il modo più rapido per provare SnapOtter o auto-ospitarlo su un homelab. Per la produzione, esegui lo stack [Docker Compose](#docker-compose) qui sotto, che mantiene PostgreSQL e Redis nei loro container. La modalità integrata gira come root (l'impostazione predefinita) e si disattiva automaticamente non appena imposti `DATABASE_URL`.

+Stai installando su un Raspberry Pi, un vecchio laptop o un piccolo VPS? Vedi [Configurazioni a basse risorse](/it/guide/low-resource) per una guida già calibrata e per sapere cosa aspettarti da hardware limitato.
+
 Ti verrà chiesto di cambiare la password al primo login.

 ::: tip Analytics di prodotto anonime
@@ -0,0 +1,103 @@
+---
+i18n_source_hash: f5de74aee1b9
+i18n_provenance: machine
+i18n_output_hash: 81cc593eda8d
+---
+# Configurazioni a basse risorse {#low-resource-setups}
+
+SnapOtter funziona bene su hardware modesto: un Raspberry Pi 4 o 5, un vecchio laptop o un VPS da 2 GB. Questa pagina è la guida pratica per quelle macchine: cosa aspettarsi, una configurazione copia-incolla con limiti ragionevoli e quali funzionalità saltare. I dati completi dei benchmark dietro questi numeri si trovano in [Requisiti hardware](/it/guide/deployment#hardware-requirements).
+
+Due vincoli rigidi da subito:
+
+- **Solo a 64 bit.** L'immagine viene creata per `linux/amd64` e `linux/arm64`. ARM a 32 bit (`armv7`/`armhf`) non è supportato, quindi i Pi di prima generazione e la famiglia Pi Zero sono esclusi.
+- **Soglia minima di memoria: 2 GB.** Con 512 MB lo stack non si avvia nemmeno, e 1 GB fallisce sui batch multi-file. 2 GB con 2 core è la configurazione più piccola che funziona comodamente.
+
+## Cosa funziona bene su hardware modesto {#what-runs-well}
+
+Ogni strumento non AI funziona su una macchina da 2 GB / 2 core: le intere sezioni Immagine e File, gli strumenti PDF e le operazioni video e audio in stream-copy (taglio, silenziamento, remux del container). La maggior parte termina in meno di un secondo.
+
+Due carichi di lavoro fanno eccezione:
+
+- **La ricodifica video** (conversione tra codec) è vincolata alla CPU. Una clip 1080p che richiede ~40 s su una CPU desktop veloce può richiedere diversi minuti su una CPU di classe Pi. Le operazioni in stream-copy restano istantanee.
+- **Gli strumenti AI** hanno bisogno di RAM (4 GB consigliati) e di disco (i bundle più grandi pesano 4-5 GB ciascuno), e quelli pesanti (upscaling, ripristino foto, rimozione dello sfondo) non sono praticabili su CPU di classe Pi. L'AI leggera come il rilevamento dei volti e l'OCR è utilizzabile se hai la memoria necessaria.
+
+Nessuno dei due è installato o in esecuzione finché non lo usi: senza bundle AI installati l'app a riposo occupa circa 360 MB, e i bundle AI vengono scaricati solo quando un amministratore li abilita.
+
+## Guida passo passo per Raspberry Pi / vecchio laptop {#walkthrough}
+
+Questa è l'installazione Compose standard di [Per iniziare](/it/guide/getting-started), più limiti di risorse e tetti prudenti. Presuppone un sistema operativo a 64 bit (su un Pi: Raspberry Pi OS 64-bit o Ubuntu Server arm64).
+
+```yaml
+services:
+  snapotter:
+    image: snapotter/snapotter:latest
+    ports:
+      - "1349:1349"
+    volumes:
+      - ./snapotter-data:/data
+    environment:
+      - DATABASE_URL=postgres://snapotter:snapotter@db:5432/snapotter
+      - REDIS_URL=redis://redis:6379
+      # Small-box profile: see the table below for what each cap does.
+      - CONCURRENT_JOBS=1
+      - MAX_WORKER_THREADS=2
+      - MAX_BATCH_SIZE=5
+      - MAX_UPLOAD_SIZE_MB=100
+      - MAX_MEGAPIXELS=50
+      - MAX_VIDEO_DURATION_S=300
+    deploy:
+      resources:
+        limits:
+          cpus: "2"
+          memory: 2G
+    depends_on:
+      - db
+      - redis
+    restart: unless-stopped
+
+  db:
+    image: postgres:17-alpine
+    environment:
+      - POSTGRES_USER=snapotter
+      - POSTGRES_PASSWORD=snapotter
+      - POSTGRES_DB=snapotter
+    volumes:
+      - ./postgres-data:/var/lib/postgresql/data
+    restart: unless-stopped
+
+  redis:
+    image: redis:8-alpine
+    command: redis-server --maxmemory 256mb --maxmemory-policy noeviction
+    restart: unless-stopped
+```
+
+Note per le macchine di classe Pi:
+
+- **Preferisci un SSD USB a una scheda SD** per il volume dei dati e Postgres. Gli spazi di lavoro dei job fanno vero IO su disco, e le schede SD sono lente e si usurano in fretta.
+- **Anche il container unico all-in-one funziona qui** (Postgres e Redis integrati quando `DATABASE_URL`/`REDIS_URL` non sono impostati), e su un host con poca memoria conviene abbassare il tetto del Redis integrato con `REDIS_MAXMEMORY` (vedi [Configurazione](/it/guide/configuration)). Compose offre un controllo più fine per singolo servizio, ed è per questo che questa guida lo usa.
+- **Aggiungi swap sui dispositivi da 2 GB.** Evita che il picco occasionale (un PDF enorme, un batch che hai dimenticato di limitare) finisca in un out-of-memory kill. zram è l'opzione più delicata con le schede SD.
+- L'immagine arm64 è solo CPU; non c'è CUDA sulle schede ARM.
+
+## I parametri di regolazione {#tuning-knobs}
+
+Tutti i tetti sono variabili d'ambiente, documentate per esteso in [Configurazione](/it/guide/configuration). `0` significa illimitato o automatico. Quelli che contano su hardware modesto:
+
+| Variabile | Suggerimento per macchine piccole | Cosa protegge |
+|---|---|---|
+| `CONCURRENT_JOBS` | `1` | Quanti job girano in parallelo. Il rilevamento automatico usa i core della CPU meno uno, che va bene sulle macchine grandi ed è troppo aggressivo su una macchina a 2 core sotto pressione di memoria. |
+| `MAX_WORKER_THREADS` | `2` | Pool di thread per l'elaborazione delle immagini. |
+| `MAX_BATCH_SIZE` | `5` | I batch sono il punto in cui le macchine da 1-2 GB esauriscono la memoria per prime. |
+| `MAX_UPLOAD_SIZE_MB` | `100` | Impedisce che un singolo file enorme occupi l'intero spazio di lavoro. |
+| `MAX_MEGAPIXELS` | `50` | Decodificare un'immagine da 100+ MP costa RAM a prescindere dalla dimensione del file. |
+| `MAX_VIDEO_DURATION_S` | `300` | Le transcodifiche lunghe monopolizzano una CPU piccola per minuti o ore. |
+| `PROCESSING_TIMEOUT_S` | `600` | Tetto rigido perché un job fuori controllo liberi comunque la macchina, prima o poi. |
+
+Questi tetti si applicano a ciò che il server accetta, quindi impostali in base a ciò che usi davvero, non al minimo possibile. Se non tocchi mai i video, un tetto su `MAX_VIDEO_DURATION_S` non costa nulla; se digitalizzi documenti ogni giorno, non mettere un tetto a `MAX_PDF_PAGES`.
+
+## Cosa saltare {#what-to-skip}
+
+- **I bundle AI pesanti.** Upscaling, ripristino foto e rimozione dello sfondo vogliono una GPU o una CPU veloce con molti core, e ogni bundle costa 4-5 GB di disco. Su una macchina piccola, semplicemente non installarli; gli strumenti il cui bundle manca mostrano un invito all'installazione invece di essere eseguiti.
+- **La ricodifica video come carico di lavoro abituale.** Le transcodifiche occasionali vanno bene (sono solo lente); una coda di transcodifica costante vuole core CPU, non un Pi.
+- **Gli strumenti inutilizzati in generale.** Un amministratore può disattivare i singoli strumenti nelle Impostazioni, il che li rimuove dall'interfaccia e smette di registrare le loro rotte API. Di per sé non fa risparmiare memoria, ma evita che una piccola istanza condivisa venga usata proprio per l'unico carico di lavoro che l'hardware non può reggere.
+
+Se in seguito sposti l'istanza su hardware più potente, rimuovi i tetti (riportali a `0`) e lo stesso volume dei dati si trasferisce così com'è.
@@ -1,7 +1,7 @@
 ---
 description: "Guida al rafforzamento della sicurezza per SnapOtter. Sicurezza del container, isolamento di rete, Docker secrets, distribuzione Kubernetes e artefatti di conformità."
 i18n_source_hash: 986f7658430c
-i18n_provenance: machine
+i18n_provenance: human
 i18n_output_hash: 24c63a8f7f16
 ---