La passerelle refuse de démarrer

La passerelle refuse de démarrer quand une variable indispensable est absente, plutôt que de démarrer avec un repli. C’est délibéré : un repli était juste sur un poste et faux en production, où il transformait une variable oubliée en conteneur qui démarrait, passait ses sondes, et échouait sur chaque requête avec une erreur qui ne nommait jamais la variable en cause.

Le message de démarrage nomme donc ce qui manque. Commencez par le lire.

DATABASE_URL est absente

La passerelle lit sa configuration — endpoints, fournisseurs, clés — dans sa base. Sans adresse de base, elle n’a rien à servir.

export DATABASE_URL="postgresql://<utilisateur>:<mot-de-passe>@<hôte>:<port>/<base>"

Cas particulier d’une base managée. Certaines refusent le mode sslmode=require attendu par le client PostgreSQL et demandent sslmode=no-verify :

export DATABASE_URL="postgresql://…/proxy?sslmode=no-verify"

ADMIN_API_KEY est absente

C’est la clé qui protège les routes d’administration. La passerelle refuse de démarrer sans elle, pour qu’aucune installation ne se retrouve avec une surface d’administration ouverte.

export ADMIN_API_KEY="…"

Elle démarre, mais chaque requête échoue

Le symptôme est différent : la passerelle est saine, c’est le relais vers le fournisseur qui casse. Deux causes fréquentes.

La clé du fournisseur n’est pas définie. Le nom de la variable attendue n’est pas figé dans le code : il est inscrit en base, dans la colonne api_key_env du fournisseur. Une omission ne se voit donc qu’à la première requête. Relevez le nom attendu dans la console d’administration, puis définissez-la.

Le réseau sortant passe par un proxy d’entreprise. La passerelle utilise le client HTTP natif de la plateforme et n’applique pas HTTPS_PROXY ni NODE_EXTRA_CA_CERTS. Derrière un pare-feu sortant, elle ne joint aucun fournisseur. C’est une limitation connue, sans contournement documenté à ce jour : signalez-la, elle est suivie.

Vérifier que la passerelle répond

Il n’existe pas de route de santé dédiée. Le contrôle en usage consiste à appeler une route inexistante et à vérifier qu’elle répond 401 — ce qui prouve que le service écoute et que l’authentification s’applique :

curl -s -o /dev/null -w '%{http_code}\n' http://<hôte>:<port>/healthz/v1/messages

Une réponse 401 est le résultat attendu. Une absence de réponse signifie que le service n’écoute pas.