Documentazione

Questa documentazione è pensata per gli amministratori che ospitano Wanmory su un NAS, un server domestico o un computer personale. Copre installazione, configurazione, servizio IA, uso quotidiano, impostazioni di sistema e manutenzione. Per la progettazione del sistema e gli algoritmi, vedi Architettura.

Wanmory è una fototeca privata con IA, open source e self-hosted. È composta da quattro container: il backend in Go (server), il servizio di inferenza IA in Python (ml), il database PostgreSQL + pgvector (postgres) e mdns, che annuncia il dominio locale. Foto, metadati, vettori e coda dei lavori sono tutti salvati in locale, senza dipendere da alcun servizio cloud.

• Gestione foto: cronologia raggruppata per mese, album e album intelligenti, riordino di raffiche e foto simili, mappa dei viaggi e presentazioni.
• Funzioni IA: rilevamento e raggruppamento dei volti, ricerca in linguaggio naturale (Chinese-CLIP), riconoscimento del testo (PP-OCR) e valutazione estetica (scelte dell’IA).
• Più membri: account individuali, permessi di eliminazione in base a chi ha caricato e cronologia degli accessi.

Metodo 1: script di installazione (consigliato)

Su una macchina a 64 bit con Docker installato, esegui:

curl -fsSL https://wanmory.com/install.sh | bash

Lo script fa quanto segue, nell’ordine:

• Controllo dell’ambiente: architettura CPU (amd64 / arm64) e userland a 64 bit, disponibilità di Docker e Docker Compose v2, memoria e spazio su disco liberi.
• Configurazione interattiva: cartella di installazione (predefinita ~/wanmory), porta di accesso (predefinita 8080, controlla se è occupata), dominio locale (predefinito wanmory.local), password del database (casuale per impostazione predefinita) e posizione del database (volume Docker pgdata per impostazione predefinita, oppure una cartella su un disco locale), fuso orario (scrivi una città o una regione per cercarla, come shanghai, tokyo o 北京, e scegli un numero se ci sono più risultati).
• Posizioni di archiviazione: cartella dei dati (miniature, anteprime e foto caricate, predefinita ./data) e cartella dei modelli IA (predefinita ./models).
• Le domande e i messaggi dello script sono in inglese, così si vedono correttamente in qualsiasi terminale di NAS.
• Cartelle di foto esistenti: aggiungine quante vuoi, scegliendo per ciascuna il montaggio in sola lettura (consigliato) o in lettura e scrittura.
• Crea .env (permessi 600); se indichi cartelle di foto, crea anche docker-compose.override.yml, che Docker Compose unisce automaticamente.
• Scarica il docker-compose.yml ufficiale (da Gitee se GitHub non risponde), verifica la configurazione, scarica le immagini, avvia i servizi e mostra l’indirizzo quando tutto è pronto.

# Esempio: installazione non interattiva in /opt/wanmory sulla porta 9000, con le cartelle foto del NAS
curl -fsSL https://wanmory.com/install.sh | WANMORY_PORT=9000 WANMORY_PHOTOS=/volume1/photo,/volume2/family bash -s -- -y --dir /opt/wanmory

Metodo 2: installazione manuale

1. 1
   Crea una cartella e scarica il file Compose

   Crea una cartella per il file Compose, i dati e i modelli, e scarica il docker-compose.yml ufficiale:

   bashCopia

   mkdir -p ~/wanmory && cd ~/wanmory
   curl -fsSLO https://raw.githubusercontent.com/i-dj/wanmory/main/docker/docker-compose.yml

2. 2
   (Facoltativo) Scrivi un .env

   Crea un .env nella stessa cartella per cambiare i valori predefiniti. In produzione cambia assolutamente la password del database:

   .envCopia

   WANMORY_DB_PASSWORD=sostituisci-con-una-stringa-casuale
   WANMORY_PORT=8080
   WANMORY_TZ=Europe/Rome
   WANMORY_VERSION=latest

3. 3
   Avvia i servizi

   Il primo avvio scarica le immagini ed esegue in automatico le migrazioni del database:

   bashCopia

   docker compose up -d
   docker compose ps        # verifica che tutti e quattro i servizi siano running / healthy

4. 4
   Apri e configura

   Apri http://wanmory.local:8080 (o http://<IP dell’host>:8080) nel browser, crea l’account amministratore come indicato, poi scarica i modelli in «Impostazioni di sistema → IA». Una volta scaricati, le foto esistenti entrano da sole nella coda IA.

Il file Compose ufficiale definisce quattro servizi: il database postgres, il backend server, l’annuncio del dominio locale mdns e il servizio IA integrato ml. Il ruolo di ogni impostazione è annotato direttamente nel file:

# File Compose ufficiale di Wanmory: esegui docker compose up -d nella cartella di questo file
# Le variabili nella forma ${VAR:-predefinito} si leggono dal .env nella stessa cartella; se mancano, vale il predefinito
services:
  # ── Database: PostgreSQL 17 + pgvector ───────────────────────────
  # Conserva metadati delle foto, persone, album, impostazioni, coda dei lavori e vettori (indice HNSW)
  # Nessuna porta pubblicata; raggiungibile solo dalla rete interna di Compose
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: wanmory
      POSTGRES_PASSWORD: ${WANMORY_DB_PASSWORD:-wanmory}   # in produzione cambiala assolutamente nel .env
      POSTGRES_DB: wanmory
    volumes:
      - ${WANMORY_DB_DIR:-pgdata}:/var/lib/postgresql/data  # volume con nome pgdata per impostazione predefinita; con WANMORY_DB_DIR, quella cartella. Includila nei backup
    healthcheck:                             # server attende questo controllo e parte quando il database è pronto
      test: ["CMD", "pg_isready", "-U", "wanmory", "-d", "wanmory"]
      interval: 5s
      timeout: 3s
      retries: 20
    restart: unless-stopped
  # ── Backend: programma Go con l'app web incorporata ──────────────
  # Gestisce API, caricamenti (tus), pianificazione dei lavori, miniature e permessi; migra il database all'avvio
  server:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    environment:
      DATABASE_URL: postgres://wanmory:${WANMORY_DB_PASSWORD:-wanmory}@postgres:5432/wanmory
      WANMORY_ML_URL: http://ml:3003         # indirizzo del servizio IA integrato; uno remoto si imposta in «Impostazioni IA»
      TZ: ${WANMORY_TZ:-Asia/Shanghai}       # fuso orario usato se l'EXIF non lo indica
      WANMORY_MDNS: "off"                    # sulla rete bridge questo container non riceve il multicast; il dominio lo annuncia il servizio mdns qui sotto
      WANMORY_HTTP_PUBLIC_PORT: ${WANMORY_PORT:-8080}   # porta mostrata nell'app web; deve coincidere con la mappatura delle porte
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # dominio locale iniziale; una volta cambiato nelle impostazioni web, vale l'impostazione
    ports:
      - "${WANMORY_PORT:-8080}:8080"         # porta dell'host:porta del container
    volumes:
      - ${WANMORY_DATA_DIR:-./data}:/data    # upload/ contiene gli originali caricati, thumbs/ le miniature e le anteprime da 1440 px
      # Monta le cartelle di foto esistenti come sottocartelle di /photos, quante vuoi; :ro = sola lettura; scansionate ogni 15 minuti
      # - /mnt/nas/photos:/photos/nas:ro
      # - /media/usb/fotocamera:/photos/usb:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
  # ── Annuncio del dominio locale (mDNS) ───────────────────────────
  # Stessa immagine di server, esegue solo il sottocomando mdns; annuncia wanmory.local (modificabile nell'app web)
  mdns:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    command: ["mdns"]
    network_mode: host                       # serve la rete dell'host per inviare e ricevere multicast in rete locale
    environment:
      WANMORY_URL: http://127.0.0.1:${WANMORY_PORT:-8080}   # chiede periodicamente a server il dominio attuale
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # annunciato finché server non risponde
    depends_on:
      - server
    restart: unless-stopped
  # ── Servizio IA integrato: FastAPI + ONNX Runtime, solo CPU ──────
  # Senza stato; riceve le anteprime da server e restituisce volti, vettori e testo; nessuna porta pubblicata
  ml:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-ml:${WANMORY_VERSION:-latest}
    volumes:
      - ${WANMORY_MODELS_DIR:-./models}:/models  # conserva i modelli: ricreare il container non li riscarica
    environment:
      WANMORY_MODEL_DIR: /models
      WANMORY_AUTO_DOWNLOAD: "0"             # nessun download automatico; un amministratore conferma prima licenze e spazio nell'app web
    restart: unless-stopped
volumes:
  pgdata:

.env (variabili di Compose)

Queste variabili sono usate in docker-compose.yml; scrivile nel .env della stessa cartella per applicarle:

Container server (facoltativo)

DATABASE_URL, WANMORY_ML_URL, WANMORY_MDNS e WANMORY_HTTP_PUBLIC_PORT sono già impostate nel file Compose con il loro scopo annotato. Le variabili seguenti non sono nel file predefinito; aggiungile all’environment di server se servono:

Le foto già presenti su un NAS o un disco esterno non vanno caricate. Monta la cartella come sottocartella di /photos nel container: viene scansionata ogni 15 minuti e i nuovi file vengono importati sul posto (senza copiarli né spostarli), poi passano per metadati, miniature ed elaborazione IA come le foto caricate.

  server:
    volumes:
      - ./data:/data
      - /mnt/nas/photos:/photos/nas:ro       # :ro monta in sola lettura
      - /media/usb/fotocamera:/photos/usb:ro
      - /home/io/Immagini:/photos/pictures    # montaggio in lettura e scrittura

Dopo la modifica esegui docker compose up -d. La prima scansione parte circa 20 secondi dopo il riavvio del container.

• Si consiglia il montaggio in sola lettura (:ro): il sistema non scrive nulla in queste cartelle. Eliminare una foto nell’app la sposta solo in «Eliminate di recente», l’eliminazione definitiva non cancella mai il file originale e le scansioni successive non lo reimportano. Per le cartelle in lettura e scrittura, l’eliminazione definitiva cancella anche il file originale.
• I file con contenuto identico vengono importati una sola volta (confronto tramite checksum SHA-1), compresi quelli già caricati e i duplicati tra cartelle diverse.
• Le cartelle nascoste e le cartelle di sistema del NAS (.xxx, @eaDir, #recycle ecc.) vengono saltate automaticamente.
• Le foto importate dalle cartelle non appartengono ad alcun membro; solo gli amministratori possono eliminarle.

Il servizio mdns gira in modalità rete dell’host e annuncia il dominio di accesso in rete locale (predefinito wanmory.local). macOS, iOS, iPadOS e Windows 10 o successivi raggiungono http://wanmory.local:8080 senza configurare il router. Il dominio si cambia in «Impostazioni di sistema → Dominio di accesso» e deve terminare con .local.

I caricamenti web usano il protocollo riprendibile tus (/api/uploads/) con blocchi da 16 MB. Dietro un reverse proxy, togli il limite di dimensione delle richieste e disattiva il buffering delle richieste. Esempio Nginx:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}
location /api/uploads/ {
    proxy_pass http://127.0.0.1:8080;
    client_max_body_size 0;          # nessun limite di dimensione (almeno 20m)
    proxy_request_buffering off;     # inoltro in streaming, senza salvare sul disco del proxy
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Il servizio IA è un servizio HTTP senza stato: riceve dal backend anteprime da 1440 pixel e restituisce volti, vettori e testo riconosciuto. Non accede mai al database e non salva file. Il backend prevede due modalità, che si cambiano in «Impostazioni di sistema → IA → Modalità di esecuzione IA»:

Se il servizio IA non è disponibile, i lavori IA restano in coda e non vengono più presi, senza consumare tentativi; quando il servizio torna, l’elaborazione riprende da sola. Navigazione, caricamenti e il resto non ne risentono.

Metodo 1: direttamente su un Mac o una macchina con GPU (consigliato)

Eseguito direttamente, il servizio sfrutta l’accelerazione hardware: su Apple Silicon i modelli per i volti usano CoreML e Chinese-CLIP usa MPS; sulle GPU NVIDIA Chinese-CLIP usa CUDA a mezza precisione (circa 1,9 GB di VRAM / memoria). Installa prima uv.

git clone https://github.com/i-dj/wanmory.git
cd wanmory/ml
uv sync --extra torch                 # installa le dipendenze PyTorch (ricerca semantica accelerata da GPU)
# Genera un token di accesso; backend e servizio IA usano lo stesso valore
export WANMORY_ML_TOKEN=$(openssl rand -hex 24)
echo $WANMORY_ML_TOKEN
WANMORY_FACE_MODEL_PRELOAD=1 uv run --extra torch python -m wanmory_ml
# Ascolta su 0.0.0.0:3003 per impostazione predefinita; si cambia con WANMORY_ML_HOST / WANMORY_ML_PORT

Metodo 2: l’immagine Docker su un’altra macchina

Per una macchina x86 più potente senza GPU utilizzabile; l’immagine usa solo la CPU:

docker run -d --name wanmory-ml --restart unless-stopped \
  -p 3003:3003 \
  -e WANMORY_ML_TOKEN=<token-di-accesso> \
  -v $PWD/models:/models \
  ghcr.io/i-dj/wanmory-ml:latest

Attivare il servizio remoto nel backend

1. 1
   Apri le impostazioni IA

   Come amministratore, vai in «Impostazioni di sistema → IA → Modalità di esecuzione IA» e scegli «Servizio remoto».

2. 2
   Inserisci indirizzo e token

   L’indirizzo ha la forma http://192.168.1.20:3003; inserisci il token generato al passaggio precedente. Prima di salvare la connessione viene provata, con latenza e versione del servizio.

3. 3
   Conferma livello e modelli

   Una volta connesso, un livello «Automatico» viene ricalcolato in base all’hardware della macchina remota; scarica i modelli necessari in «Livello dei modelli».

Il livello determina quali modelli si usano per volti e ricerca semantica. Con «Automatico», il sistema consiglia un livello in base all’hardware della macchina del servizio IA: «Alta precisione» con una GPU utilizzabile; con sola CPU, «Leggero» sotto i 6 GB di memoria, altrimenti «Equilibrato».

• Il riconoscimento del testo usa PP-OCRv6 (RapidOCR); i suoi modelli si installano con le dipendenze, senza download a parte.
• Dopo il cambio di livello, i volti di tutte le foto vengono rilevati di nuovo e i vettori semantici ricalcolati con i nuovi modelli; nel frattempo la ricerca continua con i vettori vecchi e le persone con nome restano.
• I modelli vengono scaricati nella cartella montata ./models, e quelli non più usati si possono eliminare per liberare spazio (il modello in uso non si può eliminare).
• I modelli per i volti InsightFace sono solo per uso non commerciale; sostituiscili o ottieni una licenza prima di qualsiasi uso commerciale.

1. 1
   Crea l’amministratore

   Al primo accesso il sistema vede che non ci sono account e guida nella creazione di un amministratore. Gli amministratori possono aggiungere membri e cambiare le impostazioni di sistema.

2. 2
   Scarica i modelli

   Vai in «Impostazioni di sistema → IA», conferma il livello dei modelli e scaricali. Finché non sono pronti, i lavori IA aspettano in coda.

3. 3
   Importa le foto

   Caricale dall’app web oppure collega le foto del NAS come descritto in Montare cartelle di foto esistenti.

4. 4
   Aggiungi membri

   In «Impostazioni di sistema → Membri», crea gli account delle altre persone e scegli il ruolo «Membro» o «Amministratore».

• Il caricamento web accetta foto, video, HEIC, RAW (come DNG) e altro, con selezione multipla; il caricamento avviene a blocchi con il protocollo tus e riprende dopo un’interruzione di rete o un ricaricamento della pagina.
• I file caricati vengono salvati per anno e mese nella cartella dei caricamenti (predefinita data/upload). La cartella si cambia in «Impostazioni di sistema → Cartella dei caricamenti» e vale solo per i nuovi caricamenti.
• Dopo l’importazione si eseguono nell’ordine: lettura dei metadati (ExifTool) → miniature e anteprima da 1440 pixel (libvips / FFmpeg) → vettori semantici, volti e testo (servizio IA) → geocodifica inversa.
• L’indicatore dei lavori in cima alla barra laterale mostra, in numero di foto, avanzamento e tempo residuo stimato di «Importazione foto» e «Riconoscimento IA».

Le informazioni sulle persone (nomi, unioni) sono comuni a tutti i membri; numero di foto, copertine e pagine delle persone si calcolano sulle foto che ogni membro può vedere, e le foto nascoste le vede solo chi le ha nascoste.

• Membri: quando ne aggiungi uno, imposti nome, password iniziale (almeno 4 caratteri) e ruolo; puoi reimpostare la password di un membro o rimuoverlo.
• Cronologia accessi: registra ora, dispositivo e IP di ogni accesso, con la posizione stimata offline dall’IP (ip2region), e conserva gli ultimi sei mesi. La vedono solo gli amministratori.
• In «Il mio account» ogni membro può cambiare password e avatar e vedere i dispositivi su cui ha effettuato l’accesso.

In cima alla scheda si vede in tempo reale lo stato dell’IA (in funzione o motivo della pausa). Le modifiche valgono subito, senza riavvio.

«Impostazioni di sistema → Aggiornamento di sistema» mostra le versioni attuali del backend e del servizio IA e segnala quelle nuove. Per aggiornare, esegui nella cartella che contiene docker-compose.yml:

docker compose pull && docker compose up -d

Le migrazioni del database partono da sole all’avvio di server. Se hai fissato una versione con WANMORY_VERSION, cambia prima il tag nel .env.

I dati da salvare sono di tre tipi:

# Esportare il database
docker compose exec -T postgres pg_dump -U wanmory -Fc wanmory > wanmory-$(date +%F).dump
# Ripristinare in una nuova installazione (prima esegui docker compose up -d postgres)
docker compose exec -T postgres pg_restore -U wanmory -d wanmory --clean < wanmory-2026-11-10.dump

Quando un membro dimentica la password, un amministratore la reimposta in «Impostazioni di sistema → Membri». Se l’amministratore dimentica la propria, esegui sull’host dell’app, nella cartella che contiene docker-compose.yml:

docker compose exec server wanmory reset-password            # elenca gli account e scegline uno
docker compose exec server wanmory reset-password <nome>      # indica direttamente l'account

• Il comando elenca tutti gli account (nome, ruolo, data di creazione, ultimo accesso); scegline uno con il numero e inserisci due volte la nuova password.
• Dopo la reimpostazione l’account viene disconnesso da tutti i dispositivi; foto e album non cambiano.
• Si può fare solo sull’host, l’app web non lo prevede. Senza Docker, esegui wanmory reset-password con le stesse variabili d’ambiente del server, come DATABASE_URL.

I log dei servizi si vedono con docker compose logs -f server e docker compose logs -f ml. Se il problema persiste, scrivici dalla pagina Segnala un problema indicando versione e log pertinenti.

Esegui lo script di disinstallazione sull’host dove gira Wanmory:

curl -fsSL https://wanmory.com/uninstall.sh | bash

Lo script legge prima il .env nella cartella di installazione ed elenca container, database, cartella dei dati e modelli IA con lo spazio occupato, oltre alle cartelle di foto montate. Poi ferma e rimuove container e rete e chiede, voce per voce, se eliminare (per impostazione predefinita si tiene tutto):

• Le cartelle di foto montate (NAS, dischi esterni) non vengono mai eliminate.
• Per eliminare il database o la cartella dei dati bisogna digitare DELETE come conferma.
• Se rimuovi solo i container e tieni i dati, rieseguire install.sh nella stessa cartella ripristina tutto; se elimini il .env ma tieni il database, annota prima il WANMORY_DB_PASSWORD che contiene.