Databases, Systems & Networks

Si votre maison brûle ou est cambriolée, pourrez-vous dire à votre assureur ce que vous possédiez, combien ça valait et où c’était rangé ? La plupart d’entre nous répondraient « à peu près ». HomeBox est un outil libre, léger et auto-hébergé qui sert précisément à remplacer ce « à peu près » par un inventaire précis, avec photos, factures et notices.

À quoi sert HomeBox ?

HomeBox est un système d’inventaire et d’organisation pensé pour les particuliers. C’est la suite du projet HomeBox d’origine, aujourd’hui maintenue par SysAdmins Media sous licence AGPL v3. Il est écrit en Go, utilise SQLite et embarque son interface web : un seul conteneur suffit, sans base de données externe à administrer.

Ses usages typiques :

• Justifier un sinistre auprès de l’assurance : liste des biens, photos, prix et dates d’achat, numéros de série, factures et garanties au même endroit.
• Savoir où sont les choses : chaque objet est rattaché à un emplacement (pièce, meuble, étagère, boîte), ce qui évite le « on en a déjà un quelque part ».
• Suivre garanties et entretien : dates d’achat, fin de garantie, échéances de maintenance.
• Conserver la documentation : notices, éclatés, catalogues, manuels, joints directement à la fiche de l’objet.
• Gérer un atelier ou une collection : outillage, machines, composants, avec des champs personnalisés (référence, marque, état, etc.).

Ce qu’il fait concrètement

• Organisation par emplacements (hiérarchiques), étiquettes et champs personnalisés.
• Recherche rapide dans tout l’inventaire.
• Photos et pièces jointes (documents, garanties, factures).
• Informations d’achat : date, prix, vendeur, durée de garantie.
• Import et export CSV : on peut partir d’un tableur existant et ressortir ses données à tout moment.
• Génération d’étiquettes avec QR code à coller sur les boîtes et les rangements.
• Interface utilisable sur ordinateur, tablette et téléphone.
• API REST, point de contrôle de santé (utile pour la supervision) et client MQTT pour les intégrations domotiques.

Pourquoi l’auto-héberger ?

Un inventaire pour l’assurance contient la liste de tout ce qui a de la valeur chez vous, avec photos. C’est typiquement une donnée que l’on préfère garder chez soi plutôt que sur un service tiers. Il n’y a ni abonnement, ni limite d’objets, ni suivi. Contrepartie : la sauvegarde devient votre responsabilité, et il faut qu’elle soit hors de la maison, sinon un incendie emporte l’inventaire avec le reste (voir la section sauvegarde).

Installation avec Docker

Prérequis

• Une machine Linux avec Docker et le plugin Docker Compose.
• Un dossier pour l’application, par exemple /opt/homebox.
• Idéalement un reverse proxy avec HTTPS (surtout si vous voulez ajouter des photos depuis un téléphone, les navigateurs sont plus restrictifs sans HTTPS).

Les besoins en ressources sont très modestes : de l’ordre de 128 à 256 Mo de mémoire.

1. Préparer les dossiers et le « pepper »

Le pepper est une valeur secrète utilisée par HomeBox pour protéger les clés d’API. Le projet demande d’en définir un.

sudo mkdir -p /opt/homebox/data
cd /opt/homebox

# Génère le pepper et l'enregistre dans un fichier .env réservé à son propriétaire
printf 'HBOX_AUTH_API_KEY_PEPPER=%s\n' "$(openssl rand -base64 48)" | sudo tee .env > /dev/null
sudo chmod 600 .env

2. Écrire le fichier docker-compose.yml

services:
  homebox:
    image: ghcr.io/sysadminsmedia/homebox:latest
    container_name: homebox
    restart: unless-stopped
    environment:
      - TZ=Europe/Paris
      - HBOX_AUTH_API_KEY_PEPPER=${HBOX_AUTH_API_KEY_PEPPER}
    ports:
      - "127.0.0.1:3100:7745"
    volumes:
      - ./data:/data

Points à noter :

• L’application écoute sur le port 7745 dans le conteneur. Ici il est publié sur le port 3100 de la machine, uniquement sur 127.0.0.1 : c’est le reverse proxy qui l’exposera. Pour un test rapide sans proxy, remplacez par "3100:7745".
• Le volume /data contient la base SQLite et les pièces jointes. C’est le seul dossier à sauvegarder.
• Trois variantes d’image existent : latest, latest-rootless et latest-hardened. Les deux dernières ne tournent pas en root ; le dossier de données doit alors appartenir à l’utilisateur 65532 :

sudo chown -R 65532:65532 /opt/homebox/data

3. Démarrer

cd /opt/homebox
docker compose up -d
docker compose logs -f homebox

L’interface est alors disponible sur http://adresse-de-la-machine:3100 (ou via votre reverse proxy).

4. Premier accès

1. Ouvrez l’interface et créez votre compte depuis la page d’inscription ; le premier compte est celui du propriétaire.
2. Une fois vos comptes créés, fermez les inscriptions en ajoutant cette variable dans la section environment du compose, puis docker compose up -d à nouveau :

      - HBOX_OPTIONS_ALLOW_REGISTRATION=false

3. Créez vos emplacements (maison, pièces, meubles) avant de saisir les objets : c’est ce qui rend l’inventaire utile.

5. Reverse proxy (exemple Apache)

Si vous publiez HomeBox en HTTPS sur un nom de domaine interne, un hôte virtuel Apache minimal ressemble à ceci (modules proxy, proxy_http, ssl et headers activés) :

<VirtualHost *:443>
    ServerName homebox.exemple.lan
    SSLEngine on
    SSLCertificateFile    /chemin/fullchain.pem
    SSLCertificateKeyFile /chemin/privkey.pem

    ProxyPreserveHost On
    RequestHeader set X-Forwarded-Proto "https"
    ProxyPass        / http://127.0.0.1:3100/
    ProxyPassReverse / http://127.0.0.1:3100/
</VirtualHost>

Si vous préférez Nginx, Caddy ou Traefik, le principe est identique : tout transférer vers le port 3100 en conservant l’en-tête Host.

Remplir l’inventaire sans y passer des semaines

Saisir des centaines d’objets à la main décourage. Quelques pistes :

• Import CSV : si vous avez déjà un tableur (outillage, matériel, meubles), exportez d’abord un CSV depuis HomeBox pour voir le format attendu, alignez vos colonnes dessus, puis importez.
• Photo d’abord, détails ensuite : prendre une photo de chaque pièce, rangement ouvert, vaut mieux qu’aucun inventaire. On complète les objets de valeur en priorité.
• Objets de valeur et factures : joindre systématiquement la facture et le numéro de série, c’est ce que demandera l’assureur.
• Étiquettes QR : à coller sur les boîtes de rangement pour retrouver leur contenu depuis le téléphone.

Sauvegarde : le point à ne pas négliger

Tout est dans le dossier data (base SQLite et pièces jointes). Trois niveaux de protection :

1. Copie locale régulière : arrêtez brièvement le conteneur ou utilisez la sauvegarde SQLite avant de copier la base, pour ne pas copier un fichier en cours d’écriture.

cd /opt/homebox
docker compose stop homebox
tar czf /var/backups/homebox-$(date +%F).tar.gz data
docker compose start homebox

2. Export CSV depuis l’interface : un filet de sécurité lisible par n’importe quel tableur, indépendant de HomeBox.
3. Copie hors site : sur un cloud chiffré, un disque emporté ailleurs ou le NAS d’un proche. Sans elle, l’inventaire « en cas de sinistre » disparaît justement en cas de sinistre.

Mises à jour

Le projet évolue vite et progresse vers une version 1 stable. Avant toute montée de version :

1. Faites une sauvegarde complète du dossier data.
2. Lisez les notes de version sur la page GitHub du projet : certaines versions modifient la base de données et peuvent ne pas permettre le retour en arrière.
3. Mettez à jour :

cd /opt/homebox
docker compose pull
docker compose up -d

Pour éviter les surprises, vous pouvez remplacer latest par un numéro de version précis dans le fichier compose et ne changer ce numéro que lorsque vous êtes prêt.

Mon retour d’expérience

Je fais tourner HomeBox depuis octobre 2026 sur hanuc2, mon serveur Docker à la maison. Mon objectif est simple : pouvoir justifier auprès de mon assureur, en cas de sinistre, de tout ce que contient la maison. J’ai suivi le modèle de mes autres applications (Wallos, Paperless-ngx) : un dossier sous /opt, un conteneur, un hôte virtuel Apache.

Mes choix, qui s’écartent un peu de l’installation de base décrite plus haut :

• Accès : HomeBox écoute sur 127.0.0.1:7745 et n’est joignable que via Apache, en HTTPS, sur un nom interne. Rien n’est exposé sur Internet, l’application reste réservée au réseau local.
• Base en local, pièces jointes sur le NAS : la base SQLite reste sur le disque du serveur, et seules les pièces jointes (le dossier /data) vont sur mon NAS Synology, via un partage dédié monté en CIFS sur le serveur. Au-delà de la place disponible, c’est aussi une bonne pratique : SQLite supporte mal d’être placé sur un partage réseau.
• Un compte dédié sur le NAS : j’ai créé un utilisateur et un partage homebox, dont l’accès est limité à ce seul compte, pour que l’application ne voie rien d’autre sur le NAS.
• Pepper obligatoire : le fichier .env contient HBOX_AUTH_API_KEY_PEPPER, que le projet demande de définir.
• Inscriptions fermées après la création de mon compte.
• Sauvegarde quotidienne de la base par un timer systemd, chaque nuit à 04h10, vers un dossier de sauvegardes du serveur.

Remplir l’inventaire

Je n’avais aucune envie de saisir à la main tous les objets de la maison. J’ai donc importé en CSV mon tableur d’outillage et de machines, puis je rattache les photos, notices, catalogues et éclatés que je possède déjà, rangés par marque, type et modèle dans mon iCloud Drive. L’objectif est d’avoir, sur chaque fiche, tous les fichiers de l’objet et pas seulement la notice. Certains fichiers n’étant qu’« dans le nuage », il faut d’abord les télécharger localement avant de pouvoir les envoyer.

Ce qu’il me reste à faire

La copie hors site des pièces jointes n’est pas encore en place : je l’ai reportée (piste Zerobyte, ou Hyper Backup côté NAS). C’est le maillon faible de mon installation actuelle, pour la raison évoquée plus haut : un inventaire destiné à l’assurance doit survivre à la maison.

Pour conclure

HomeBox n’a rien de spectaculaire, et c’est son intérêt : un conteneur, un volume, une interface claire, et au bout du compte un inventaire qui peut faire gagner beaucoup de temps le jour où l’on en a vraiment besoin. L’essentiel du travail n’est pas l’installation (dix minutes), mais la saisie initiale et la discipline de sauvegarde hors site.

Sources :

• Dépôt GitHub de HomeBox (SysAdmins Media)
• Site officiel du projet
• Fiche HomeBox sur Linux Server Admin Wiki
• Fiche HomeBox sur LinuxLinks