Documentation

Cette documentation s’adresse aux administrateurs qui auto-hébergent Wanmory sur un NAS, un serveur domestique ou un ordinateur personnel. Elle couvre l’installation, la configuration, le déploiement du service IA, l’usage quotidien, les réglages système et l’exploitation. Pour la conception du système et les algorithmes, voir Architecture.

Wanmory est une photothèque IA privée, open source et auto-hébergée. Elle se compose de quatre conteneurs : le backend Go (server), le service d’inférence IA en Python (ml), la base PostgreSQL + pgvector (postgres) et mdns, qui annonce le domaine local. Photos, métadonnées, vecteurs et file de tâches sont tous stockés en local, sans dépendre d’aucun service cloud.

• Gestion des photos : chronologie groupée par mois, albums et albums intelligents, tri des rafales et photos similaires, carte des voyages, diaporamas.
• Fonctions IA : détection et regroupement des visages, recherche en langage naturel (Chinese-CLIP), reconnaissance de texte (PP-OCR), note esthétique (sélection IA).
• Plusieurs membres : comptes individuels, droits de suppression liés à la propriété, historique des connexions.

Méthode 1 : script d’installation (recommandé)

Sur une machine 64 bits équipée de Docker, exécutez :

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

Le script effectue ensuite les opérations suivantes :

• Vérification de l’environnement : architecture CPU (amd64 / arm64) et espace utilisateur 64 bits, disponibilité de Docker et de Docker Compose v2, mémoire et espace disque libres.
• Configuration interactive : dossier d’installation (par défaut ~/wanmory), port d’accès (par défaut 8080, vérifié s’il est libre), domaine local (par défaut wanmory.local), mot de passe de la base (aléatoire par défaut) et emplacement de la base (volume Docker pgdata par défaut, ou un dossier sur un disque local), fuseau horaire (tapez une ville ou une région pour chercher, comme shanghai, tokyo ou 北京, puis choisissez un numéro s’il y a plusieurs résultats).
• Emplacements de stockage : dossier de données (miniatures, aperçus et photos importées, par défaut ./data) et dossier des modèles IA (par défaut ./models).
• Les questions et messages du script sont en anglais pour s’afficher correctement dans tous les terminaux de NAS.
• Dossiers photo existants : ajoutez-en autant que vous voulez, en choisissant pour chacun un montage en lecture seule (recommandé) ou en lecture-écriture.
• Écrit .env (droits 600) ; si des dossiers photo sont indiqués, il écrit aussi docker-compose.override.yml, que Docker Compose fusionne automatiquement.
• Télécharge le docker-compose.yml officiel (via Gitee si GitHub est injoignable), valide la configuration, récupère les images, démarre les services et affiche l’adresse dès que tout est prêt.

# Exemple : installation non interactive dans /opt/wanmory, port 9000, avec les dossiers photo du NAS
curl -fsSL https://wanmory.com/install.sh | WANMORY_PORT=9000 WANMORY_PHOTOS=/volume1/photo,/volume2/family bash -s -- -y --dir /opt/wanmory

Méthode 2 : installation manuelle

1. 1
   Créer un dossier et récupérer le fichier Compose

   Créez un dossier pour le fichier Compose, les données et les modèles, puis téléchargez le docker-compose.yml officiel :

   bashCopier

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

2. 2
   (Facultatif) Écrire un .env

   Créez un .env dans le même dossier pour remplacer les valeurs par défaut. En production, changez impérativement le mot de passe de la base :

   .envCopier

   WANMORY_DB_PASSWORD=remplacez-par-une-chaine-aleatoire
   WANMORY_PORT=8080
   WANMORY_TZ=Europe/Paris
   WANMORY_VERSION=latest

3. 3
   Démarrer les services

   Le premier démarrage télécharge les images et exécute automatiquement les migrations de la base :

   bashCopier

   docker compose up -d
   docker compose ps        # vérifier que les quatre services sont running / healthy

4. 4
   Ouvrir et initialiser

   Ouvrez http://wanmory.local:8080 (ou http://<IP de l’hôte>:8080) dans un navigateur, créez le compte administrateur comme indiqué, puis téléchargez les modèles dans « Réglages système → IA ». Une fois les modèles prêts, les photos existantes entrent automatiquement dans la file de traitement IA.

Le fichier Compose officiel définit quatre services : la base postgres, le backend server, l’annonceur de domaine local mdns et le service IA intégré ml. Le rôle de chaque réglage est indiqué directement dans le fichier :

# Fichier Compose officiel de Wanmory : lancez docker compose up -d dans le dossier de ce fichier
# Les variables de la forme ${VAR:-défaut} sont lues dans le .env du même dossier ; sinon la valeur par défaut s'applique
services:
  # ── Base de données : PostgreSQL 17 + pgvector ───────────────────
  # Stocke métadonnées des photos, personnes, albums, réglages, file de tâches et vecteurs (index HNSW)
  # Aucun port publié ; joignable uniquement sur le réseau interne de Compose
  postgres:
    image: pgvector/pgvector:pg17
    environment:
      POSTGRES_USER: wanmory
      POSTGRES_PASSWORD: ${WANMORY_DB_PASSWORD:-wanmory}   # à changer impérativement dans .env en production
      POSTGRES_DB: wanmory
    volumes:
      - ${WANMORY_DB_DIR:-pgdata}:/var/lib/postgresql/data  # volume nommé pgdata par défaut ; avec WANMORY_DB_DIR, ce dossier. À inclure dans les sauvegardes
    healthcheck:                             # server attend ce contrôle de santé et démarre une fois la base prête
      test: ["CMD", "pg_isready", "-U", "wanmory", "-d", "wanmory"]
      interval: 5s
      timeout: 3s
      retries: 20
    restart: unless-stopped
  # ── Backend : binaire Go avec l'application web intégrée ─────────
  # Gère l'API, les imports (tus), l'ordonnancement, les miniatures et les droits ; migre la base au démarrage
  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         # adresse du service IA intégré ; un service distant se règle dans « Réglages IA »
      TZ: ${WANMORY_TZ:-Asia/Shanghai}       # fuseau utilisé quand l'EXIF n'en contient pas
      WANMORY_MDNS: "off"                    # ce conteneur ne reçoit pas le multicast sur le réseau bridge ; le service mdns ci-dessous annonce le domaine
      WANMORY_HTTP_PUBLIC_PORT: ${WANMORY_PORT:-8080}   # port affiché dans l'app web, à aligner sur la redirection de port
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # domaine local initial ; une fois modifié dans les réglages web, c'est le réglage qui prime
    ports:
      - "${WANMORY_PORT:-8080}:8080"         # port de l'hôte:port du conteneur
    volumes:
      - ${WANMORY_DATA_DIR:-./data}:/data    # upload/ contient les originaux importés, thumbs/ les miniatures et aperçus 1440 px
      # Montez les dossiers photo existants comme sous-dossiers de /photos, autant que voulu ; :ro = lecture seule ; analyse toutes les 15 minutes
      # - /mnt/nas/photos:/photos/nas:ro
      # - /media/usb/appareil:/photos/usb:ro
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped
  # ── Annonce du domaine local (mDNS) ──────────────────────────────
  # Même image que server, n'exécute que la sous-commande mdns ; annonce wanmory.local (modifiable dans l'app web)
  mdns:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-server:${WANMORY_VERSION:-latest}
    command: ["mdns"]
    network_mode: host                       # le réseau de l'hôte est nécessaire pour émettre et recevoir le multicast local
    environment:
      WANMORY_URL: http://127.0.0.1:${WANMORY_PORT:-8080}   # demande régulièrement le domaine actuel à server
      WANMORY_DOMAIN: ${WANMORY_DOMAIN:-wanmory.local}  # annoncé tant que server est injoignable
    depends_on:
      - server
    restart: unless-stopped
  # ── Service IA intégré : FastAPI + ONNX Runtime, CPU uniquement ──
  # Sans état ; reçoit les aperçus de server et renvoie visages, vecteurs et texte ; aucun port publié
  ml:
    image: ${WANMORY_REGISTRY:-ghcr.io/i-dj}/wanmory-ml:${WANMORY_VERSION:-latest}
    volumes:
      - ${WANMORY_MODELS_DIR:-./models}:/models  # conserve les modèles : recréer le conteneur ne les retélécharge pas
    environment:
      WANMORY_MODEL_DIR: /models
      WANMORY_AUTO_DOWNLOAD: "0"             # pas de téléchargement automatique ; un admin valide d'abord licences et espace disque dans l'app web
    restart: unless-stopped
volumes:
  pgdata:

.env (variables Compose)

Ces variables sont utilisées dans docker-compose.yml ; placez-les dans le .env du même dossier pour les appliquer :

Conteneur server (facultatif)

DATABASE_URL, WANMORY_ML_URL, WANMORY_MDNS et WANMORY_HTTP_PUBLIC_PORT sont déjà définis dans le fichier Compose, avec leur rôle. Les variables suivantes n’y figurent pas ; ajoutez-les au besoin dans l’environment de server :

Les photos déjà présentes sur un NAS ou un disque externe n’ont pas besoin d’être importées. Montez le dossier comme sous-dossier de /photos dans le conteneur : il est analysé toutes les 15 minutes, les nouveaux fichiers sont importés sur place (ni copiés ni déplacés), puis passent par la lecture des métadonnées, la génération des miniatures et le traitement IA comme les photos importées.

  server:
    volumes:
      - ./data:/data
      - /mnt/nas/photos:/photos/nas:ro       # :ro monte en lecture seule
      - /media/usb/appareil:/photos/usb:ro
      - /home/moi/Images:/photos/pictures     # montage en lecture-écriture

Après modification, lancez docker compose up -d. La première analyse commence environ 20 secondes après le redémarrage du conteneur.

• Le montage en lecture seule (:ro) est recommandé : rien n’est écrit dans ces dossiers. Supprimer une photo dans l’app la déplace seulement vers « Supprimées récemment », la suppression définitive n’efface jamais le fichier d’origine, et les analyses suivantes ne le réimportent pas. Pour les dossiers en lecture-écriture, la suppression définitive efface aussi le fichier d’origine.
• Les fichiers au contenu identique ne sont importés qu’une fois (dédoublonnage par somme SHA-1), y compris les fichiers déjà importés et les doublons entre dossiers.
• Les dossiers cachés et les dossiers système de NAS (.xxx, @eaDir, #recycle, etc.) sont ignorés automatiquement.
• Les photos venant des dossiers photo n’appartiennent à aucun membre ; seuls les administrateurs peuvent les supprimer.

Le service mdns fonctionne en mode réseau hôte et annonce le domaine d’accès sur le réseau local (par défaut wanmory.local). macOS, iOS, iPadOS et Windows 10 ou plus récent y accèdent via http://wanmory.local:8080 sans configurer le routeur. Le domaine se change dans « Réglages système → Domaine d’accès » et doit se terminer par .local.

Les imports web utilisent le protocole avec reprise tus (/api/uploads/) par blocs de 16 Mo. Derrière un proxy inverse, levez la limite de taille des requêtes et désactivez la mise en tampon. Exemple 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;          # aucune limite de taille (au moins 20m)
    proxy_request_buffering off;     # transmettre en flux plutôt que de tamponner sur le disque du proxy
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Le service IA est un service HTTP sans état : il reçoit des aperçus de 1440 pixels du backend et renvoie visages, vecteurs et texte reconnu. Il n’accède jamais à la base et ne stocke aucun fichier. Le backend propose deux modes, à choisir dans « Réglages système → IA → Mode d’exécution IA » :

Si le service IA est indisponible, les tâches IA restent en file et ne sont plus prises, sans consommer de relances ; le traitement reprend automatiquement au retour du service. La navigation, les imports et le reste ne sont pas affectés.

Méthode 1 : directement sur un Mac ou une machine avec GPU (recommandé)

Exécuté directement, le service profite de l’accélération matérielle : sur Apple Silicon, les modèles de visages utilisent CoreML et Chinese-CLIP utilise MPS ; sur GPU NVIDIA, Chinese-CLIP utilise CUDA en demi-précision (environ 1,9 Go de mémoire vidéo / vive). Installez d’abord uv.

git clone https://github.com/i-dj/wanmory.git
cd wanmory/ml
uv sync --extra torch                 # installer les dépendances PyTorch (recherche sémantique accélérée par GPU)
# Générer un jeton d'accès ; le backend et le service IA utilisent la même valeur
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
# Écoute sur 0.0.0.0:3003 par défaut ; modifiable avec WANMORY_ML_HOST / WANMORY_ML_PORT

Méthode 2 : image Docker sur une autre machine

Pour une machine x86 plus puissante sans GPU exploitable ; l’image n’utilise que le processeur :

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

Activer le service distant dans le backend

1. 1
   Ouvrir les réglages IA

   En tant qu’administrateur, ouvrez « Réglages système → IA → Mode d’exécution IA » et choisissez « Service distant ».

2. 2
   Saisir l’adresse et le jeton

   L’adresse ressemble à http://192.168.1.20:3003 ; saisissez le jeton généré à l’étape précédente. La connexion est testée avant l’enregistrement, avec affichage de la latence et de la version du service.

3. 3
   Vérifier le niveau et les modèles

   Une fois connecté, un niveau « Automatique » est réévalué selon le matériel de la machine distante ; téléchargez les modèles nécessaires dans « Niveau de modèles ».

Le niveau détermine les modèles utilisés pour les visages et la recherche sémantique. En « Automatique », le système recommande un niveau selon le matériel de la machine du service IA : « Précision » avec un GPU exploitable ; sur processeur seul, « Léger » sous 6 Go de mémoire, sinon « Équilibré ».

• La reconnaissance de texte utilise PP-OCRv6 (RapidOCR) ; ses modèles s’installent avec les dépendances, sans téléchargement séparé.
• Après un changement de niveau, les visages de toutes les photos sont redétectés et les vecteurs sémantiques recalculés avec les nouveaux modèles ; la recherche continue d’utiliser les anciens vecteurs entre-temps, et les personnes nommées sont conservées.
• Les modèles sont téléchargés dans le dossier ./models monté ; ceux qui ne servent plus peuvent être supprimés pour libérer de la place (sauf le modèle en cours d’utilisation).
• Les modèles de visages InsightFace sont réservés à un usage non commercial ; remplacez-les ou obtenez une licence avant tout usage commercial.

1. 1
   Créer l’administrateur

   À la première visite, le système constate qu’aucun compte n’existe et guide la création d’un administrateur. Les administrateurs peuvent ajouter des membres et modifier les réglages système.

2. 2
   Télécharger les modèles

   Ouvrez « Réglages système → IA », confirmez le niveau de modèles et téléchargez-les. Les tâches IA attendent en file jusqu’à ce que les modèles soient prêts.

3. 3
   Importer des photos

   Importez via l’app web, ou branchez les photos de votre NAS comme décrit dans Monter des dossiers photo existants.

4. 4
   Ajouter des membres

   Dans « Réglages système → Membres », créez des comptes pour les autres personnes et choisissez le rôle « Membre » ou « Administrateur ».

• L’import web accepte photos, vidéos, HEIC, RAW (comme DNG) et plus, en sélection multiple ; l’envoi se fait par blocs avec le protocole tus et reprend après une coupure réseau ou un rechargement de la page.
• Les fichiers importés sont rangés par année et par mois dans le dossier d’import (par défaut data/upload). Ce dossier se change dans « Réglages système → Dossier d’import » et ne s’applique qu’aux nouveaux imports.
• Après l’import, les étapes s’enchaînent : lecture des métadonnées (ExifTool) → miniatures et aperçu de 1440 pixels (libvips / FFmpeg) → vecteurs sémantiques, visages et texte (service IA) → géocodage inverse.
• L’indicateur de tâches en haut de la barre latérale affiche, en nombre de photos, l’avancement et le temps restant estimé pour « Importer des photos » et « Reconnaissance IA ».

Les informations sur les personnes (noms, fusions) sont partagées par tous les membres ; le nombre de photos, les vignettes et les pages des personnes sont calculés d’après les photos que chaque membre peut voir, et les photos masquées ne sont visibles que de leur propriétaire.

• Membres : à l’ajout, définissez un nom, un mot de passe initial (au moins 4 caractères) et un rôle ; vous pouvez réinitialiser le mot de passe d’un membre ou le retirer.
• Historique des connexions : enregistre l’heure, l’appareil et l’IP de chaque connexion, la position étant estimée hors ligne d’après l’IP (ip2region), et conserve les six derniers mois. Visible des administrateurs uniquement.
• Dans « Mon compte », chaque membre peut changer son mot de passe et son avatar et voir les appareils sur lesquels il est connecté.

Le haut de la carte affiche en direct l’état de l’IA (en marche, ou raison de la pause). Les modifications s’appliquent immédiatement, sans redémarrage.

« Réglages système → Mise à jour » affiche les versions actuelles du backend et du service IA et signale les nouvelles versions. Pour mettre à jour, exécutez dans le dossier contenant docker-compose.yml :

docker compose pull && docker compose up -d

Les migrations de la base s’exécutent automatiquement au démarrage de server. Si vous avez fixé une version avec WANMORY_VERSION, modifiez d’abord l’étiquette dans .env.

Trois types de données sont à sauvegarder :

# Exporter la base de données
docker compose exec -T postgres pg_dump -U wanmory -Fc wanmory > wanmory-$(date +%F).dump
# Restaurer dans un nouveau déploiement (lancer d'abord docker compose up -d postgres)
docker compose exec -T postgres pg_restore -U wanmory -d wanmory --clean < wanmory-2026-11-10.dump

Quand un membre oublie son mot de passe, un administrateur le réinitialise dans « Réglages système → Membres ». Si l’administrateur oublie le sien, exécutez sur l’hôte de l’app, dans le dossier contenant docker-compose.yml :

docker compose exec server wanmory reset-password            # lister les comptes et en choisir un
docker compose exec server wanmory reset-password <nom>       # désigner directement le compte

• La commande liste tous les comptes (nom, rôle, date de création, dernière connexion) ; choisissez-en un par son numéro et saisissez deux fois le nouveau mot de passe.
• Après la réinitialisation, ce compte est déconnecté de tous les appareils ; photos et albums ne sont pas touchés.
• Cette opération ne se fait que sur l’hôte, l’app web n’en offre pas l’accès. Sans Docker, exécutez wanmory reset-password avec les mêmes variables d’environnement que le serveur, comme DATABASE_URL.

Consultez les journaux de chaque service avec docker compose logs -f server et docker compose logs -f ml. Si le problème persiste, signalez-le sur la page Signaler un problème en joignant votre numéro de version et les journaux pertinents.

Exécutez le script de désinstallation sur l’hôte où tourne Wanmory :

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

Le script lit d’abord le .env du dossier d’installation et liste les conteneurs, la base, le dossier de données et les modèles IA avec l’espace qu’ils occupent, ainsi que les dossiers photo montés. Il arrête et supprime ensuite les conteneurs et le réseau, puis demande élément par élément s’il faut supprimer (tout est conservé par défaut) :

• Les dossiers photo montés (NAS, disques externes) ne sont jamais supprimés.
• Supprimer la base ou le dossier de données exige de taper DELETE pour confirmer.
• Si vous ne supprimez que les conteneurs en gardant les données, relancer install.sh dans le même dossier restaure tout ; si vous supprimez .env en gardant la base, notez d’abord le WANMORY_DB_PASSWORD qu’il contient.