Dépannage de déploiement

Quatre pannes mangent le premier déploiement. Lancez le preflight avant tout — il nomme la mauvaise configuration au lieu de vous faire deviner :

pnpm import:self-host-check

docker run --rm --env-file .env ghcr.io/capitality-io/mildport-aio \
  bun dist/cli/self-host-check.js

Sur Kubernetes, helm test mildport est le même contrôle dans le cluster.

Les images ne pullent pas (ImagePullBackOff)

Les images vivent sur ghcr.io/capitality-io/* et sont privées. Un pod coincé en ImagePullBackOff / ErrImagePull est presque toujours l’un de :

1. Accès pas encore accordé. Demandez-le depuis Self-hosting dans votre compte pour l’utilisateur GitHub qui pullera. Un grant en attente ressemble à un mauvais mot de passe.

2. Le nœud n’est pas connecté. Un docker login sur le laptop n’aide pas le cluster.

   echo $GITHUB_TOKEN | docker login ghcr.io -u <your-github-username> --password-stdin

   Sur Kubernetes, ces identifiants vont dans un imagePullSecret :

   kubectl create secret docker-registry ghcr-pull \
     --docker-server=ghcr.io \
     --docker-username=<your-github-username> \
     --docker-password=$GITHUB_TOKEN \
     -n mildport

   imagePullSecrets:
     - name: ghcr-pull

3. Mauvais registre. Nous publions sur GHCR, pas Docker Hub. Si les values disent encore capitality/mildport, le pull n’aboutira jamais. Voir Accès aux images.

Chaque import renvoie 401

401 signifie que la clé de licence n’a pas vérifié. Le corps ressemble à { "status": "error", "code": "UNAUTHORIZED", "reason": "…" }. Le reason est la correction :

reason	Signification	À faire
missing	Pas d’en-tête Authorization: Bearer …	Passez la clé depuis Licences
not_configured	Le moteur n’a pas IMPORT_LICENSE_PUBLIC_KEY	Collez la clé publique de Self-hosting ; redémarrez
expired	Le exp de la clé est dans le passé	Régénérez sur Licences ; l’ancienne reste jusqu’à expiration
revoked	L’id de licence est sur IMPORT_LICENSE_REVOKED_IDS	Retirez-le, ou utilisez une nouvelle clé
malformed / bad_signature / bad_attestation	Clé tronquée, espaces en trop, ou d’un autre émetteur	Recopiez la clé ; n’en émettez pas une vous-même

Une clé publique absente est aussi un échec de readiness (checks.license: missing) — le moteur répond /health et 401 chaque import quand même.

Pas un 401 :

• 403 ORIGIN_NOT_ALLOWED — la clé est valide, mais elle a été émise avec une liste d’origines qui n’inclut pas cette page. Régénérez avec les bonnes origines (ou une liste vide). Ce n’est pas du CORS.
• CORS dans le navigateur — la requête n’obtient jamais de corps JSON. Section suivante.

Confirmez une clé contre un moteur en marche avec GET /api/import/v1/license/verify. Plus sur les clés : Licences.

Le widget ne fait rien (CORS)

L’image de production (NODE_ENV=production) refuse toute requête navigateur cross-origin quand ALLOWED_ORIGINS est vide — y compris http://localhost:5173. Le localhost en mode dev n’est autorisé que hors production.

Réglez l’origine exacte de la page qui embarque le widget, schéma et port compris :

ALLOWED_ORIGINS=https://app.example.com,http://localhost:5173

Sur Helm, c’est app.allowedOrigins. Les appelants serveur à serveur (pas d’en-tête Origin) ne sont pas concernés ; omettez la variable seulement si rien dans un navigateur ne parle au moteur.

La liste d’origines de la clé (403 ORIGIN_NOT_ALLOWED) est un second verrou, distinct. Le CORS décide si le navigateur peut parler ; la clé décide si cette origine peut utiliser cette clé.

Le pod ne devient jamais Ready

GET /health est la liveness. Il renvoie {"status":"ok","service":"mildport",…} dès que le processus peut répondre, avant Mongo ou les licences. La sonde de readiness du chart est GET /health/ready. Un pod qui vit mais n’est jamais Ready échoue cette sonde.

curl -i localhost:8090/health/ready

503 avec un corps :

{
  "status": "not_ready",
  "service": "mildport",
  "checks": { "mongo": "down", "license": "missing" }
}

Check	down / missing signifie	Correction
mongo	Le moteur ne peut pas pinger Mongo (URI fausse, network policy, Mongo à l’arrêt)	MONGO_CONNECTION_STRING ; attendre Mongo ; helm test
license	Pas de clé publique et mode développement off	IMPORT_LICENSE_PUBLIC_KEY depuis la page Self-hosting

license: dev-mode est ready — les clés synthétiques marchent, et vous ne devriez pas livrer ça.

Des sidecars down ne font pas échouer la readiness. Des URL de decode non définies veulent seulement dire que ces familles de fichiers sont refusées. Un PDF qui 503 pendant que /health/ready est 200 est une URL de sidecar, pas un pod coincé.

Suite : Votre premier import · Configuration · Accès aux images