Risoluzione dei problemi di deployment

Quattro fallimenti si mangiano il primo deploy. Esegui il preflight prima di qualsiasi altra cosa — nomina la configurazione sbagliata invece di farti indovinare:

pnpm import:self-host-check

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

Su Kubernetes, helm test mildport è lo stesso controllo dentro il cluster.

Le immagini non fanno pull (ImagePullBackOff)

Le immagini vivono su ghcr.io/capitality-io/* e sono private. Un pod bloccato in ImagePullBackOff / ErrImagePull è quasi sempre uno di:

1. Accesso non ancora concesso. Richiedilo da Self-hosting nel tuo account per l’utente GitHub che farà pull. I grant in attesa sembrano una password sbagliata.

2. Il nodo non è loggato. Un docker login sul laptop non aiuta il cluster.

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

   Su Kubernetes quelle credenziali vanno in 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. Registry sbagliato. Pubblichiamo su GHCR, non Docker Hub. Se i values dicono ancora capitality/mildport, il pull non riuscirà mai. Vedi Accesso alle immagini.

Ogni import restituisce 401

401 significa che la chiave di licenza non ha verificato. Il body sembra { "status": "error", "code": "UNAUTHORIZED", "reason": "…" }. Il reason è la correzione:

reason	Cosa significa	Cosa fare
missing	Nessun header Authorization: Bearer …	Passa la chiave da Licenze
not_configured	Il motore non ha IMPORT_LICENSE_PUBLIC_KEY	Incolla la chiave pubblica da Self-hosting; riavvia
expired	L’exp della chiave è nel passato	Rigenera su Licenze; la vecchia vale fino alla scadenza
revoked	L’id di licenza è su IMPORT_LICENSE_REVOKED_IDS	Toglilo, o usa una chiave nuova
malformed / bad_signature / bad_attestation	Chiave troncata, spazi extra, o di un altro issuer	Copia di nuovo la chiave; non emetterne una tu

Una chiave pubblica assente è anche un fallimento di readiness (checks.license: missing) — il motore risponde /health e comunque dà 401 a ogni import.

Non è un 401:

• 403 ORIGIN_NOT_ALLOWED — la chiave è valida, ma è stata emessa con una lista di origini che non include questa pagina. Rigenera con le origini giuste (o una lista vuota). Questo non è CORS.
• CORS nel browser — la richiesta non ottiene mai un body JSON. Sezione successiva.

Conferma una chiave contro un motore in esecuzione con GET /api/import/v1/license/verify. Altro sulle chiavi: Licenze.

Il widget non fa niente (CORS)

L’immagine di produzione (NODE_ENV=production) rifiuta ogni chiamata browser cross-origin quando ALLOWED_ORIGINS è vuoto — incluso http://localhost:5173. Il localhost in modalità dev è consentito solo fuori dalla produzione.

Imposta l’origine esatta della pagina che incorpora il widget, schema e porta compresi:

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

Su Helm è app.allowedOrigins. I chiamanti server-to-server (nessun header Origin) non sono toccati; ometti la variabile solo se niente in un browser parla con il motore.

La lista di origini della chiave (403 ORIGIN_NOT_ALLOWED) è un secondo lucchetto, a parte. Il CORS decide se il browser può parlare; la chiave decide se quell’origine può usare questa chiave.

Il pod non diventa mai Ready

GET /health è liveness. Restituisce {"status":"ok","service":"mildport",…} appena il processo può rispondere, prima di Mongo o le licenze. La sonda di readiness del chart è GET /health/ready. Un pod che vive ma non è mai Ready sta fallendo quella sonda.

curl -i localhost:8090/health/ready

503 con body:

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

Check	down / missing significa	Correzione
mongo	Il motore non pinga Mongo (URI sbagliata, network policy, Mongo giù)	MONGO_CONNECTION_STRING; aspetta Mongo; helm test
license	Nessuna chiave pubblica e modalità sviluppo off	IMPORT_LICENSE_PUBLIC_KEY dalla pagina Self-hosting

license: dev-mode è ready — le chiavi sintetiche funzionano, e non dovresti spedire quello.

I sidecar giù non fanno fallire la readiness. URL di decode non impostati significano solo che quelle famiglie di file vengono rifiutate. Un PDF che dà 503 mentre /health/ready è 200 è un URL di sidecar, non un pod bloccato.

Avanti: Il tuo primo import · Configurazione · Accesso alle immagini