Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

Tableau de bord web (gateway.web_dist_dir)

Le démon gateway intègre son API HTTP dans le binaire, mais les fichiers HTML/JS/CSS du tableau de bord web résident sur disque dans un répertoire web/dist/ produit par Vite. Le paramètre gateway.web_dist_dir (et son remplacement par variable d’environnement miroir du schéma ZEROCLAW_gateway__web_dist_dir) indique au démon où se trouve ce répertoire. Lorsque ni le paramètre ni un emplacement de repli connu ne contient un index.html compilé, la gateway démarre en mode API uniquement et l’URL du tableau de bord renvoie un message « non disponible ».

TL;DR

sh

# Équivalent de surcharge par variable d'environnement (en mémoire uniquement, jamais persisté)
export ZEROCLAW_gateway__web_dist_dir="/absolute/path/to/zeroclaw/web/dist"

Compilez ensuite le bundle une seule fois :

sh

cargo web build

…et redémarrez le démon. Le journal de démarrage passe de

Web dashboard: not available — no web/dist found. Build with `cargo web build` …

à

Web dashboard: serving from /absolute/path/to/zeroclaw/web/dist

Ce que fait le paramètre

gateway.web_dist_dir est une Option<String> qui pointe vers le répertoire contenant un fichier index.html compilé. Au démarrage de la passerelle, le démon :

  1. Lit la valeur configurée (ou la valeur de remplacement issue de la variable d’environnement).
  2. Vérifie que le répertoire existe ET contient index.html sur cette machine.
  3. Si oui, sert le tableau de bord depuis ce chemin.
  4. Si non, journalise un WARN (« le chemin ne contient pas index.html sur cette machine ; retour à la détection automatique ») et essaie les candidats de détection automatique ci-dessous.
  5. Si la détection automatique ne donne rien non plus, la passerelle fonctionne en mode API uniquement et GET / renvoie un message « not available » qui redirige vers cette page.

La valeur est traitée comme une indication, et non comme une exigence stricte. Un chemin obsolète (faute de frappe, chemin propre à un hôte copié depuis une autre machine, build manquant) bascule en détection automatique plutôt que de faire échouer chaque requête du tableau de bord.

Par défaut : détection automatique de l’ordre

Lorsque gateway.web_dist_dir n’est pas défini (ou pointe vers un chemin sans index.html), le démon teste ces emplacements dans l’ordre et sert le contenu du premier qui contient index.html :

#CandidatLorsqu’elle correspond
1./web/dist (relatif au CWD)Exécuter cargo run depuis la racine du dépôt en dev
2<dir-of-binary>/web/distLe binaire packagé fournit web/dist à côté de lui-même
3/zeroclaw-data/web/distStructure standard Docker / volume packagé
4/usr/share/zeroclawlabs/web/distInstallation du paquet AUR / système
5${XDG_DATA_HOME:-~/.local/share}/zeroclaw/web/distProgramme d’installation de binaire précompilé (par utilisateur)

Si vous utilisez l’une de ces distributions et que le tableau de bord « fonctionne tout simplement », vous n’avez pas du tout besoin de définir gateway.web_dist_dir, la détection automatique l’a trouvé.

Comment obtenir un web/dist

Vous avez trois options. Choisissez celle qui correspond à la façon dont vous avez installé ZeroClaw.

A) Récupération des sources (développeurs / mainteneurs de paquets)

sh

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
cargo web build           # alias pour `cargo run -p xtask --bin web -- build`
                          # exécute automatiquement `npm install` au premier lancement

Le bundle est généré dans web/dist/. Faites pointer web_dist_dir vers le chemin absolu de ce répertoire, ou exécutez le daemon depuis la racine du dépôt et laissez le candidat 1 de la détection automatique le récupérer.

L’ensemble complet des sous-commandes cargo web (dev, check, gen-api, etc.) est documenté dans Building the web dashboard.

B) Artefact de version pré-compilé

Les archives de version disponibles sur la page Releases fournissent le daemon avec web/dist/ déjà rempli aux côtés du binaire. Le candidat 2 de détection automatique le trouve ; aucune configuration gateway.web_dist_dir n’est nécessaire.

C) Image Docker

L’image Docker officielle place le bundle dans /zeroclaw-data/web/dist (candidat de détection automatique 3). Elle fonctionne immédiatement ; vous n’avez besoin de définir web_dist_dir que si vous montez votre propre volume sur ce chemin.

Priorité de remplacement

La valeur est résolue selon l’ordre standard des couches de configuration :

  1. ZEROCLAW_gateway__web_dist_dir (variable d’environnement reflétant le schéma, voir Variables d’environnement)
  2. Le gateway.web_dist_dir configuré
  3. Détection automatique (les cinq candidats ci-dessus)

Les remplacements par variables d’environnement s’appliquent uniquement à la Config en mémoire ; ils ne sont jamais persistés.

Grammaire schema-mirror : dérivation de ZEROCLAW_gateway__web_dist_dir

La grammaire générale de remplacement des opérateurs (voir Variables d’environnement) associe le chemin TOML pointé à un nom de variable d’environnement de manière mécanique :

TOML path:  gateway.web_dist_dir
            ─────── ─────────────
            section field-name (snake_case, kept as-is)

Env var:    ZEROCLAW_gateway__web_dist_dir
            ─────────       ──            ────────────
            prefix          path-separator  field-name
                            (`.` → `__`)    (unchanged)

Les trois mêmes étapes produisent des noms de variables d’environnement pour tous les autres paramètres de la passerelle, p. ex. gateway.request_timeout_secs devient ZEROCLAW_gateway__request_timeout_secs.

Pièges courants

N’utilisez pas ~ ou $HOME

Un tilde littéral n’est pas développé par la passerelle ; utilisez un chemin absolu pour gateway.web_dist_dir. Les variables shell ($HOME, %USERPROFILE%) ne sont pas non plus développées ; pré-développez-les dans la variable d’environnement si vous définissez la valeur de cette façon :

sh

export ZEROCLAW_gateway__web_dist_dir="$HOME/zeroclaw/web/dist"   # shell expands $HOME

La PR compagnon #6961 ajoute la vérification ciblée « ressemble à un ~ / $VAR non développé, appliquez shellexpand avant d’écrire cette valeur » suivie dans l’issue #6079 à la fois à zeroclaw doctor et à zeroclaw self-test en tant que diagnostic de sévérité Warn. Aucune des deux commandes ne le signale sur le master actuel ; en attendant que la #6961 soit fusionnée, développez vous-même ~ / $VAR avant d’écrire gateway.web_dist_dir (par exemple, écrivez /home/alice/zeroclaw/web/dist au lieu de ~/zeroclaw/web/dist).

Les chemins relatifs sont résolus par rapport au CWD, et non au fichier de configuration

web_dist_dir = "web/dist" est interprété relativement au répertoire de travail du démon au moment du démarrage, et non relativement à l’emplacement du fichier de configuration. Si vous déployez une configuration sur un autre hôte ou si vous invoquez le démon depuis un répertoire différent (p. ex. via systemd), la forme relative cherchera au mauvais endroit. Utilisez des chemins absolus pour web_dist_dir.

Avertissement « Chemin obsolète » au démarrage

WARN gateway.web_dist_dir points at a path that doesn't contain index.html
on this machine; falling back to auto-detect. Update or remove the setting
to silence this warning.

Cela signifie que le chemin est syntaxiquement valide mais que le fichier n’est pas encore présent. Vous pouvez soit exécuter cargo web build, corriger le chemin, ou supprimer entièrement le paramètre et laisser la détection automatique s’en charger.

« Web dashboard: not available » au démarrage

INFO Web dashboard: not available — no web/dist found. Build with
`cargo web build` and point gateway.web_dist_dir at the resulting
web/dist directory.

Les points de terminaison de l’API fonctionnent toujours, seul le bundle HTML/JS est manquant. Compilez-le (option A/B/C ci-dessus) ou définissez le chemin.

Voir aussi