Self-hosting: panoramica

Mildport gira nella tua infrastruttura — come stack Docker Compose autonomo o su Kubernetes tramite il chart Helm. I file non lasciano mai la tua VPC, e le licenze si verificano offline — il motore non telefona mai a casa.

Lo stack

Servizio	Ruolo
mildport	Il motore di importazione + l’API REST con chiave di licenza (in ascolto su :8090).
mongo	Metadati, mappature, log di consegna.
pdf-probe	Sidecar di decodifica — estrazione di tabelle PDF.
xlsx-decode	Sidecar di decodifica — fogli di calcolo.
ocr	Sidecar di decodifica — scansioni e foto.
minio (opzionale)	Storage a oggetti compatibile S3 per file di grandi dimensioni.

Se il tuo ambiente è già Postgres, FerretDB è un’opzione sperimentale verificata — la stessa stringa di connessione, non un database di produzione per cui teniamo il supporto.

Avvialo

cp apps/import-service/.env.example apps/import-service/.env        # keys, Mongo, sidecars
docker compose --env-file apps/import-service/.env up --build

✔ mildport listening on :8090
✔ mongo · pdf-probe · xlsx-decode · ocr

Controlla lo stato:

curl localhost:8090/health
# {"status":"ok","service":"mildport"}

L’embed del widget richiede ALLOWED_ORIGINS

L’immagine di produzione imposta NODE_ENV=production e rifiuta ogni richiesta cross-origin del browser se ALLOWED_ORIGINS è vuoto — incluso localhost. Imposta le origini che incorporano il widget. Le chiamate server-to-server (senza header Origin) non sono interessate.

Preflight

Il motore include un controllo preflight che si rifiuta di farti distribuire male — convalida chiavi, storage, raggiungibilità dei sidecar ed entitlement prima di andare in produzione. Eseguilo come parte del tuo deployment:

pnpm import:self-host-check

Kubernetes (Helm)

La distribuzione include un chart Helm che deploya il motore e i sidecar di decodifica nel tuo cluster — MongoDB e S3/MinIO li porti tu. Ogni sidecar si disattiva individualmente, una modalità all-in-one raggruppa motore e i tre sidecar di decodifica in un singolo pod (il matching semantico resta un pod separato, disattivabile), e helm test esegue lo stesso preflight nel cluster prima di andare in produzione:

helm install mildport ./deploy/helm/mildport -n mildport --create-namespace \
  -f values.prod.yaml
helm test mildport -n mildport   # esegue il preflight self-host nel cluster

Insieme al chart c’è un runbook air-gap: replica le immagini nel tuo registry, imposta gli override delle immagini e ospita tu stesso il worker pdf.js — nessun accesso di rete in uscita richiesto.

In roadmap

L’hardening di Helm continua — rifinitura della gestione dei secret e flussi di installazione più fluidi per ambienti strettamente controllati.

Avanti: Il tuo primo import · Risoluzione dei problemi · Licenze.