@noeva/etl-core 1.0.0-next.2 → 1.0.0-next.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -8
- package/deploy/deploy-ecr.sh +441 -0
- package/dist/cli.js +118 -117
- package/dist/connectors/sqlserver.js +1 -1
- package/dist/etl.config.js +13 -121
- package/dist/guida/404.html +2 -2
- package/dist/guida/GUIDA_SVILUPPO.html +4 -4
- package/dist/guida/TECHNICAL_OVERVIEW.html +4 -4
- package/dist/guida/assets/{app.BMz6ZZYF.js → app.lWZ5GK2m.js} +1 -1
- package/dist/guida/assets/chunks/@localSearchIndexroot.B5zFGbAC.js +1 -0
- package/dist/guida/assets/chunks/{VPLocalSearchBox.D8gO6gDY.js → VPLocalSearchBox.C0h2R-Ih.js} +1 -1
- package/dist/guida/assets/chunks/{theme.DV62mViB.js → theme.BYWumH0G.js} +2 -2
- package/dist/guida/assets/runbooks_deploy-ecr.md.6M67F85S.js +45 -0
- package/dist/guida/assets/runbooks_deploy-ecr.md.6M67F85S.lean.js +1 -0
- package/dist/guida/assets/{runbooks_deployment.md.DvIOOsoG.js → runbooks_deployment.md.CsIYRa_5.js} +7 -5
- package/dist/guida/assets/runbooks_deployment.md.CsIYRa_5.lean.js +1 -0
- package/dist/guida/assets/{runbooks_graph-server.md.BOXZqdXC.js → runbooks_graph-server.md.opGHnuzK.js} +2 -2
- package/dist/guida/assets/{runbooks_graph-server.md.BOXZqdXC.lean.js → runbooks_graph-server.md.opGHnuzK.lean.js} +1 -1
- package/dist/guida/connectors/README.html +4 -4
- package/dist/guida/connectors/file.html +4 -4
- package/dist/guida/connectors/http.html +4 -4
- package/dist/guida/connectors/imap.html +4 -4
- package/dist/guida/connectors/jira.html +4 -4
- package/dist/guida/connectors/noeva.html +4 -4
- package/dist/guida/connectors/oauth.html +4 -4
- package/dist/guida/connectors/postgres.html +4 -4
- package/dist/guida/connectors/process.html +4 -4
- package/dist/guida/connectors/sendgrid.html +4 -4
- package/dist/guida/connectors/smtp.html +4 -4
- package/dist/guida/connectors/sqlserver.html +4 -4
- package/dist/guida/conventions/node-columns.html +4 -4
- package/dist/guida/conventions/node-descriptor.html +4 -4
- package/dist/guida/conventions/run-report.html +4 -4
- package/dist/guida/conventions/run-trace.html +4 -4
- package/dist/guida/conventions/variabili-del-core.html +4 -4
- package/dist/guida/conventions/versioni-di-pipeline.html +4 -4
- package/dist/guida/guide/claude-code/index.html +4 -4
- package/dist/guida/guide/claude-code/prompt.html +4 -4
- package/dist/guida/guide/claude-code/strumenti.html +4 -4
- package/dist/guida/guide/grafo.html +4 -4
- package/dist/guida/guide/usare/app-desktop.html +4 -4
- package/dist/guida/guide/usare/esito-di-una-run.html +4 -4
- package/dist/guida/guide/usare/index.html +4 -4
- package/dist/guida/hashmap.json +1 -1
- package/dist/guida/index.html +3 -3
- package/dist/guida/nodes/README.html +4 -4
- package/dist/guida/nodes/action.html +4 -4
- package/dist/guida/nodes/ai.html +4 -4
- package/dist/guida/nodes/join.html +4 -4
- package/dist/guida/nodes/lookup.html +4 -4
- package/dist/guida/nodes/pipeline.html +4 -4
- package/dist/guida/nodes/route.html +4 -4
- package/dist/guida/nodes/sink.html +4 -4
- package/dist/guida/nodes/source.html +4 -4
- package/dist/guida/nodes/task.html +4 -4
- package/dist/guida/nodes/transform.html +4 -4
- package/dist/guida/nodes/try-catch.html +4 -4
- package/dist/guida/nodes/union.html +4 -4
- package/dist/guida/pagine.json +1 -0
- package/dist/guida/pipelines/README.html +4 -4
- package/dist/guida/pipelines/crm-leads-sync.html +4 -4
- package/dist/guida/pipelines/cross-workspace-csv-merge.html +4 -4
- package/dist/guida/pipelines/movimenti-per-conto.html +4 -4
- package/dist/guida/pipelines/orders-enriched-daily.html +4 -4
- package/dist/guida/pipelines/test-posta.html +4 -4
- package/dist/guida/runbooks/aggiornamento-pm2.html +5 -5
- package/dist/guida/runbooks/deploy-ecr.html +71 -0
- package/dist/guida/runbooks/deployment.html +11 -9
- package/dist/guida/runbooks/etl-worker.html +4 -4
- package/dist/guida/runbooks/graph-server.html +6 -6
- package/dist/guida/runbooks/mask-key.html +4 -4
- package/dist/guida/runbooks/oauth-google-posta.html +4 -4
- package/dist/guida/runbooks/rollback-di-pipeline.html +4 -4
- package/dist/guida/runbooks/scd2-rehash.html +4 -4
- package/dist/guida/runbooks/sql-task-truncate-swap.html +4 -4
- package/dist/guida/runbooks/stato-incrementale.html +4 -4
- package/dist/guida/sub-pipelines/README.html +4 -4
- package/dist/guida/sub-pipelines/riepilogo-ordini.html +4 -4
- package/docs/.vitepress/lib/published-docs.ts +0 -21
- package/package.json +1 -2
- package/dist/chunk-DFFLQC6T.js +0 -1
- package/dist/guida/assets/chunks/@localSearchIndexroot.B3bE99g8.js +0 -1
- package/dist/guida/assets/runbooks_deployment.md.DvIOOsoG.lean.js +0 -1
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: un cliente su ECR + ECS","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/deploy-ecr.md","filePath":"runbooks/deploy-ecr.md"}'),l={name:"runbooks/deploy-ecr.md"};function t(o,i,p,h,d,r){return e(),a("div",null,[...i[0]||(i[0]=[n(`<h1 id="runbook-un-cliente-su-ecr-ecs" tabindex="-1">Runbook: un cliente su ECR + ECS <a class="header-anchor" href="#runbook-un-cliente-su-ecr-ecs" aria-label="Permalink to "Runbook: un cliente su ECR + ECS""></a></h1><blockquote><p>L'artefatto di un repo cliente è l'immagine su GHCR (<a href="./deployment">deployment.md</a>). Un cliente può scegliere invece <strong>ECR</strong>, con il suo <strong>servizio ECS</strong> e il suo <code>.env</code> in un bucket S3 (ADR-0094 §1, ADR-0104). Lo strumento arriva col pacchetto: <code>etl deploy-ecr</code>, lanciato <strong>dalla radice del repo cliente</strong>, che porta la sua <code>deploy-ecr.conf</code>.</p></blockquote><h2 id="build-pubblicazione-ecr" tabindex="-1">Build & pubblicazione (ECR) <a class="header-anchor" href="#build-pubblicazione-ecr" aria-label="Permalink to "Build & pubblicazione (ECR)""></a></h2><p>Si deploya <strong>un cliente per volta</strong>, dalla radice del suo repo:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--ambiente </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">production</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">|</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">staging]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--env </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">fil</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> [--attendi] [--dry-run]</span></span></code></pre></div><p>Lo script è il <strong>core</strong> del deploy, uguale per tutti: sta nel pacchetto, in <code>deploy/deploy-ecr.sh</code>, accanto al Dockerfile dell'artefatto. Ciò che è del cliente sta nella <code>deploy-ecr.conf</code> alla radice del suo repo, che dichiara soltanto:</p><table tabindex="0"><thead><tr><th>Variabile</th><th>Cosa</th></tr></thead><tbody><tr><td><code>ECR_REPOSITORY</code></td><td>il repository dell'immagine del cliente</td></tr><tr><td><code>ECS_CLUSTER_<amb></code>, <code>ECS_SERVICE_<amb></code>, <code>ENV_BUCKET_<amb></code></td><td>servizio e bucket del <code>.env</code> per ambiente; senza, il cliente pubblica solo l'immagine</td></tr><tr><td><code>PIPELINE</code></td><td>il catalogo del deploy, che <code>ETL_PIPELINE_WORKSPACES</code> deve assegnare per intero</td></tr><tr><td><code>ENV_OBBLIGATORIE</code>, <code>ENV_VIETATE</code></td><td>variabili che il <code>.env</code> deve avere, o non deve avere</td></tr><tr><td><code>SUBMODULE</code></td><td>submodule che l'immagine copia, verificati al commit registrato</td></tr><tr><td><code>AWS_ACCOUNT_ATTESO</code>, <code>PIATTAFORME</code></td><td>l'account su cui fermarsi se si è sbagliato profilo, e le architetture</td></tr><tr><td><code>CLIENTE_NOME</code></td><td>il nome leggibile nell'intestazione del deploy</td></tr><tr><td><code>CLIENTE_SLUG</code></td><td>lo slug del cliente: il deploy si ferma se <code><cliente></code> è un altro</td></tr></tbody></table><p>Il file è codice bash che lo script legge con <code>source</code>: solo assegnazioni, e <strong>niente segreti</strong>, che stanno nel <code>.env</code> del bucket. Un esempio:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">CLIENTE_NOME</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"Acme"</span></span>
|
|
2
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">CLIENTE_SLUG</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"acme"</span></span>
|
|
3
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">AWS_ACCOUNT_ATTESO</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"123456789012"</span></span>
|
|
4
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ECR_REPOSITORY</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"noeva-etl-acme"</span></span>
|
|
5
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">PIATTAFORME</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"amd64"</span></span>
|
|
6
|
+
<span class="line"></span>
|
|
7
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ECS_CLUSTER_production</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"cluster-production"</span></span>
|
|
8
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ECS_SERVICE_production</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"noeva-etl-acme-production"</span></span>
|
|
9
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ENV_BUCKET_production</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"noeva-etl-acme-env-production"</span></span>
|
|
10
|
+
<span class="line"></span>
|
|
11
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">PIPELINE</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">acme-ordini</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span>
|
|
12
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ENV_OBBLIGATORIE</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ACME_ORDINI_DESTINATARI</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">)</span></span></code></pre></div><p>Cosa fa, in ordine:</p><ol><li><strong>AWS</strong>: account atteso, repository ECR e servizio ECS esistenti. Non li crea: vanno creati prima (sotto, <a href="#un-cliente-su-ecs">Un cliente su ECS</a>).</li><li><strong>Git</strong>: in <code>production</code> si deploya da <code>main</code>, in <code>staging</code> da <code>staging</code>, a working tree pulito e con <code>HEAD</code> uguale a <code>origin/<branch></code>. L'immagine è sempre un commit pubblicato.</li><li><strong>Submodule</strong> dichiarati dal cliente, al commit che <code>HEAD</code> registra e senza modifiche.</li><li><strong><code>.env</code></strong>: con <code>--env <file></code> lo controlla, mostra le chiavi aggiunte e tolte rispetto a quello nel bucket (mai i valori), chiede conferma e lo carica in <code>s3://<bucket>/.env</code>. Senza, controlla quello già nel bucket. I controlli: <code>NOEVA_API_BASE_URL</code>, <code>NOEVA_API_KEY</code> e il workspace; l'URL di Noeva non locale; le obbligatorie e le vietate del cliente; <code>ETL_PIPELINE_WORKSPACES</code> che assegna tutte e sole le pipeline del cliente (ADR-0049); niente <code>export</code> né virgolette, che gli <code>environmentFiles</code> di ECS non tolgono.</li><li><strong>Gate</strong>: <code>etl ci</code>, lo stesso della CI del repo (<code>--skip-check</code> lo salta, sconsigliato).</li><li><strong>Build e push</strong> con <strong>esattamente due tag</strong>: quello di deploy (<code>latest</code> in produzione, <code>staging</code> in staging) e quello di rilascio <code>AAAAMMGG-hhmmss-<sha7></code>. Il push del tag di deploy fa partire la CodePipeline del servizio, che aggiorna ECS. Un terzo tag romperebbe la sua CodeBuild, che ricava il tag di rilascio per esclusione: lo script lo verifica dopo il push.</li><li><strong>Tag git</strong> <code>deploy/<cliente>/<ambiente>/<tag di rilascio></code>, pushato.</li><li>Con <code>--attendi</code>, aspetta la fine della CodePipeline e un servizio stabile.</li></ol><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> acme</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dry-run</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # solo i controlli</span></span>
|
|
13
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> acme</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ~/segreti/acme.env</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --attendi</span></span>
|
|
14
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> acme</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --solo-env</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ~/segreti/acme.env</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # .env nuovo, stessa immagine</span></span>
|
|
15
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> acme</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --solo-ecr</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # solo ECR, servizio non ancora creato</span></span>
|
|
16
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --help</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # tutte le opzioni</span></span></code></pre></div><p><code>--solo-ecr</code> pubblica l'immagine senza guardare il servizio ECS e il suo bucket: serve per avere l'immagine su ECR prima che il servizio esista in Terraform. Salta il controllo del <code>.env</code> nel bucket; con <code>--env <file></code> il file si controlla ma non si carica. Restano i controlli su git e submodule, il gate e i due tag: se la CodePipeline del servizio esiste già, il push del tag di deploy la fa partire comunque. Non si combina con <code>--attendi</code> né con <code>--solo-env</code>.</p><p><code>--solo-env</code> carica il <code>.env</code> e riavvia il servizio (<code>--force-new-deployment</code>) senza build: serve per cambiare i destinatari di una mail o ruotare una chiave. Il <code>.env</code> da cui si parte non sta nel repo: è del cliente, e ne esiste uno per ambiente.</p><p>La piattaforma di default è quella del cliente (<code>amd64</code> se non la dichiara), <code>--platform</code> la cambia. <code>AWS_PROFILE</code> e <code>AWS_REGION</code> (default <code>default</code>, <code>eu-west-1</code>) vengono dall'ambiente: il comando non carica il <code>.env</code> del repo.</p><p>Il gate comprende quello delle versioni di pipeline (ADR-0086), che confronta il checkout con <code>origin/dev</code> o <code>origin/main</code>: per questo lo script fa <code>git fetch origin dev main</code> prima del gate, e senza rete verso GitHub si ferma lì. Vedi <a href="./../conventions/versioni-di-pipeline#etl-versions-check">versioni di pipeline</a>.</p><h3 id="il-dockerfile" tabindex="-1">Il Dockerfile <a class="header-anchor" href="#il-dockerfile" aria-label="Permalink to "Il Dockerfile""></a></h3><p>L'immagine si costruisce col Dockerfile del pacchetto (<code>deploy/Dockerfile</code>, lo stesso di <code>image.yml</code>). Un cliente che ha bisogno di altro nell'immagine, un interprete o un CA aziendale, mette il suo <code>Dockerfile</code> alla radice del repo e lo dichiara in <code>unmanaged</code>: lo script usa quello. Se l'immagine copia dei submodule, vanno dichiarati in <code>SUBMODULE</code> e scaricati prima del deploy (<code>git submodule update --init <percorso></code>); lo script si ferma se mancano, sono a un altro commit o hanno modifiche locali.</p><p>Requisiti: AWS CLI v2, Docker con buildx, jq, git, bash, pnpm, e i submodule del cliente scaricati.</p><h2 id="un-cliente-su-ecs" tabindex="-1">Un cliente su ECS <a class="header-anchor" href="#un-cliente-su-ecs" aria-label="Permalink to "Un cliente su ECS""></a></h2><p>Il repository ECR si crea prima, con la AWS CLI (<code>aws ecr create-repository</code>, tag mutabili, scan on push, AES256). Bucket del <code>.env</code>, servizio e CodePipeline si creano in <code>noeva-terraform</code>, con lo stesso modulo <code>ecs_service</code> degli altri servizi. Un runner ETL non riceve traffico (prende i job dal poller su Noeva), quindi niente load balancer (<code>health_check_path</code> e <code>hostnames</code> a <code>null</code>, come <code>noeva-worker-api</code>), e <strong>un task solo</strong>: due <code>serve</code> prenderebbero gli stessi job due volte.</p><div class="language-hcl vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">hcl</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">module</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "noeva_etl_<cliente>_production"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
|
|
17
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> source</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "./modules/ecs_service"</span></span>
|
|
18
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> providers</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { aws </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> aws.production }</span></span>
|
|
19
|
+
<span class="line"></span>
|
|
20
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> aws_region</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> var</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">aws_region</span></span>
|
|
21
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> environment</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> var</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">environment_production</span></span>
|
|
22
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> service_name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "noeva-etl-<cliente>-production"</span></span>
|
|
23
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> service_port</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 9010</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # ETL_HTTP_PORT di \`etl serve\`</span></span>
|
|
24
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> host_port</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span></span>
|
|
25
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> service_cpu</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 256</span></span>
|
|
26
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> service_memory_reservation</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 512</span></span>
|
|
27
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> service_memory</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1024</span></span>
|
|
28
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> desired_task_count</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 1</span></span>
|
|
29
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> launch_type</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "EC2"</span></span>
|
|
30
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> minimum_healthy_percent</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 0</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # mai due worker insieme durante un deploy</span></span>
|
|
31
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> maximum_healthy_percent</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> 100</span></span>
|
|
32
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> health_check_path</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # niente load balancer: il runner non riceve traffico</span></span>
|
|
33
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> hostnames</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> null</span></span>
|
|
34
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> create_env_bucket</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
|
|
35
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> env_bucket_versioning</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> true</span></span>
|
|
36
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> env_bucket_name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "<org>-noeva-etl-<cliente>-env-production"</span></span>
|
|
37
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> create_ecr_repository</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> false</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # il repository esiste già</span></span>
|
|
38
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ecr_repository_name</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "<repository ECR del cliente>"</span></span>
|
|
39
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> deployment_tag</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> "latest"</span></span>
|
|
40
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> sns_topic_arn</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> var</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">sns_topic_arn_production</span></span>
|
|
41
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> vpc_bastion_outputs</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> module</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">vpc_bastion</span></span>
|
|
42
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> kms_outputs</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> module</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">kms</span></span>
|
|
43
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> alb_outputs</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> module</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">alb</span></span>
|
|
44
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ecs_cluster_outputs</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> module</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">.</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">ecs_cluster_production</span></span>
|
|
45
|
+
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><p>I nomi devono coincidere con quelli della <code>deploy-ecr.conf</code> del cliente. <code>service_name</code> ha al massimo 37 caratteri: il modulo ne ricava il ruolo IAM <code><service_name>-eventbridge-start-pipeline</code>, e un nome di ruolo ne ha al massimo 64. Per questo il servizio può chiamarsi diversamente dal suo repository ECR. Dopo l'<code>apply</code>:</p><ol><li>il <code>.env</code> del cliente, preparato da <code>.env.example</code> con <code>ETL_PIPELINE_WORKSPACES</code> sulle sue pipeline, va nel bucket al primo deploy (<code>--env</code>);</li><li><code>pnpm exec etl deploy-ecr <cliente> --dry-run</code> deve chiudere verde;</li><li>il primo deploy vero, con <code>--attendi</code>, poi una run di prova da Noeva.</li></ol><h2 id="la-release-nel-report" tabindex="-1">La release nel report <a class="header-anchor" href="#la-release-nel-report" aria-label="Permalink to "La release nel report""></a></h2><p>L'immagine porta <code>ETL_RELEASE=git:<sha12></code>, il commit buildato (sempre un commit pubblicato e a working tree pulito), così il report registra quale release ha eseguito la run (campo <code>release</code>; la versione di pipeline sta in <code>pipelineVersion</code>, ADR-0086). Accanto alla release il report porta la versione del core (<code>core</code>) e il cliente (<code>client</code>): vedi <a href="./../conventions/run-report#versione-di-pipeline-e-release">report di run § Versione di pipeline e release</a>.</p><h2 id="dal-repo-del-core" tabindex="-1">Dal repo del core <a class="header-anchor" href="#dal-repo-del-core" aria-label="Permalink to "Dal repo del core""></a></h2><p>Finché un cliente su ECR non ha il suo repo, la sua configurazione sta nel core, in <code>clienti/<cliente>/deploy-ecr.conf</code>, e si deploya dalla radice del core con <code>./deploy-ecr.sh <cliente></code>, che lancia lo stesso script del pacchetto. Lì il gate è <code>pnpm run check</code> e l'immagine si costruisce col <code>Dockerfile</code> del core. Lo script cerca prima la <code>deploy-ecr.conf</code> alla radice, poi quella in <code>clienti/<cliente>/</code>.</p>`,28)])])}const E=s(l,[["render",t]]);export{k as __pageData,E as default};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: un cliente su ECR + ECS","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/deploy-ecr.md","filePath":"runbooks/deploy-ecr.md"}'),l={name:"runbooks/deploy-ecr.md"};function t(o,i,p,h,d,r){return e(),a("div",null,[...i[0]||(i[0]=[n("",28)])])}const E=s(l,[["render",t]]);export{k as __pageData,E as default};
|
package/dist/guida/assets/{runbooks_deployment.md.DvIOOsoG.js → runbooks_deployment.md.CsIYRa_5.js}
RENAMED
|
@@ -1,15 +1,17 @@
|
|
|
1
|
-
import{_ as
|
|
1
|
+
import{_ as e,o as s,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const c=JSON.parse('{"title":"Runbook: distribuzione del runner ETL","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/deployment.md","filePath":"runbooks/deployment.md"}'),l={name:"runbooks/deployment.md"};function t(o,i,r,d,p,h){return s(),a("div",null,[...i[0]||(i[0]=[n(`<h1 id="runbook-distribuzione-del-runner-etl" tabindex="-1">Runbook: distribuzione del runner ETL <a class="header-anchor" href="#runbook-distribuzione-del-runner-etl" aria-label="Permalink to "Runbook: distribuzione del runner ETL""></a></h1><p>Quello che si mette in servizio è l'<strong>artefatto</strong>: il repo cliente a un commit, con il suo lockfile, che fissa anche la versione del core. Ha due <strong>confezioni</strong>, entrambe avviate con <code>etl serve</code> dalla radice del repo: l'<strong>immagine container</strong> di questo runbook, costruita dalla CI del repo cliente e pubblicata su GHCR, e <strong>PM2 dai sorgenti</strong>, in <a href="./aggiornamento-pm2">Aggiornare un deploy PM2</a>. Questo runbook copre anche la modalità <strong>batch</strong> (<code>etl run</code>, non un daemon: un container = una esecuzione di pipeline, poi termina).</p><p>Il <code>CMD</code> di default dell'immagine però è <strong><code>serve</code></strong>: server HTTP dei grafi <strong>e</strong> worker nello stesso processo, un solo container per tutta la piattaforma (runbook <a href="./graph-server">graph-server.md</a>). Il worker da solo (<code>etl worker</code>, poller sulla tabella <code>processes</code> di Noeva, anche multi-workspace) è in <a href="./etl-worker">etl-worker.md</a>: mai un container <code>worker</code> in parallelo a un <code>serve</code>, o i job vengono presi due volte.</p><p>Configurazione <strong>solo da variabili d'ambiente</strong> (nessun segreto nell'immagine).</p><blockquote><p><strong>La UI non si deploya da qui.</strong> <code>noeva-etl-ui</code> è un'app desktop Tauri, che si collega all'URL di <code>etl serve</code>: non fa parte dell'artefatto.</p></blockquote><blockquote><p><strong>Modello d'uso attuale:</strong> l'artefatto è l'immagine del repo cliente (sotto) o PM2 dai sorgenti. Un cliente può scegliere ECR + ECS invece di GHCR, con un servizio ECS suo (<a href="#un-cliente-su-ecr-ecs">§ Un cliente su ECR + ECS</a>); chi non è ancora migrato al suo repo si deploya così dal repo del core.</p></blockquote><h2 id="cli" tabindex="-1">CLI <a class="header-anchor" href="#cli" aria-label="Permalink to "CLI""></a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> list</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # elenca le pipeline disponibili</span></span>
|
|
2
2
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # esegue una pipeline</span></span>
|
|
3
3
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> serve</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # default dell'immagine: grafi via HTTP + worker</span></span>
|
|
4
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> worker</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # solo i worker</span></span
|
|
4
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> worker</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # solo i worker</span></span>
|
|
5
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # l'immagine di un cliente su ECR + ECS (sotto)</span></span></code></pre></div><p>Prima di ogni comando la CLI carica da sola il <code>.env</code> alla radice del repo, se c'è, e le variabili già nel processo vincono: <code>etl run</code> da un terminale vede lo stesso ambiente di <code>etl serve</code> sotto PM2. Nell'immagine il <code>.env</code> non c'è (lo esclude il contesto della build), e l'ambiente arriva da <code>docker run --env-file</code> o dall'orchestratore.</p><h2 id="immagine-del-repo-cliente" tabindex="-1">Immagine del repo cliente <a class="header-anchor" href="#immagine-del-repo-cliente" aria-label="Permalink to "Immagine del repo cliente""></a></h2><p>Il Dockerfile non sta nel repo cliente: lo porta il pacchetto del core, <code>@noeva/etl-core/deploy/Dockerfile</code>, con il suo <code>Dockerfile.dockerignore</code> accanto, e arriva aggiornato con il bump. L'immagine parte da <code>node:20-slim</code> e installa il repo con <code>pnpm install --prod --frozen-lockfile</code>: il core arriva dal lockfile come ogni altra dipendenza, e non c'è un'immagine base del core. Non c'è build del codice, che gira dai sorgenti con <code>tsx</code>; si costruisce invece la documentazione del cliente (<code>etl docs build</code>), che <code>etl serve</code> mostra su <code>/guida/</code>, mentre la guida del core su <code>/guida/core/</code> è già costruita nel pacchetto installato. <code>ENTRYPOINT</code> è <code>etl</code> e <code>CMD</code> è <code>serve</code>, quindi <code>… run <pipeline></code> lancia una run sola.</p><p><strong>La costruisce <code>image.yml</code></strong>, il file gestito che <code>etl init</code> scrive nel repo cliente, lanciato a mano (Actions → Immagine → Run workflow) o spingendo un tag <code>v*</code>, mai a ogni push:</p><ul><li>pubblica su <code>ghcr.io/<owner>/noeva-etl-<slug></code>, il GHCR dell'owner del repo, con <code>GITHUB_TOKEN</code>, che dopo un transfer segue il repo;</li><li><strong>il tag è lo SHA del commit</strong>, sempre, più un tag facoltativo: quello dato a mano o il tag git spinto. Niente <code>latest</code> né timestamp: il workflow rifiuta <code>latest</code>. Il deploy cita lo SHA, e il rollback del deploy è «torna allo SHA precedente»;</li><li>il core si installa da npmjs <strong>senza credenziali</strong> (ADR-0105): nessun segreto entra nella build;</li><li><code>ETL_RELEASE</code> arriva come build arg, <code>git:<sha a 12 caratteri></code>, ed è la release che il report di ogni run registra, accanto a <code>core</code> e <code>client</code>.</li></ul><p><strong>In locale</strong>, dalla radice del repo cliente e dopo <code>pnpm install</code> (il Dockerfile sta in <code>node_modules</code>):</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> build</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
5
6
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -f</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> node_modules/@noeva/etl-core/deploy/Dockerfile</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> \\</span></span>
|
|
6
7
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --build-arg</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> ETL_RELEASE=git:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rev-parse</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --short=12</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> HEAD</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>
|
|
7
8
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -t</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> noeva-etl-</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">$(</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">git</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> rev-parse</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> HEAD</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">) </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">.</span></span>
|
|
8
9
|
<span class="line"></span>
|
|
9
10
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env-file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .env</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -p</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> 3005:3005</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> noeva-etl-</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sh</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">a</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # serve</span></span>
|
|
10
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env-file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> noeva-etl-</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sh</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">a</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # una run</span></span></code></pre></div><p>Il container gira come utente <code>node</code>, e <code>.runs/</code> e <code>.state/</code> dentro <code>/app</code> sono suoi: lo storico delle run e lo stato di pipeline locale si perdono con il container, a meno di montare un volume. Un cliente che ha bisogno di altro nell'immagine (un CA aziendale, un proxy, un interprete) copia il Dockerfile nel suo repo, dichiara <code>image.yml</code> in <code>unmanaged</code> se lo modifica, e se ne assume l'aggiornamento.</p><h2 id="
|
|
11
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env-file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .env</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> noeva-etl-</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">slu</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">g</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">sh</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">a</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # una run</span></span></code></pre></div><p>Il container gira come utente <code>node</code>, e <code>.runs/</code> e <code>.state/</code> dentro <code>/app</code> sono suoi: lo storico delle run e lo stato di pipeline locale si perdono con il container, a meno di montare un volume. Un cliente che ha bisogno di altro nell'immagine (un CA aziendale, un proxy, un interprete) copia il Dockerfile nel suo repo, dichiara <code>image.yml</code> in <code>unmanaged</code> se lo modifica, e se ne assume l'aggiornamento.</p><h2 id="un-cliente-su-ecr-ecs" tabindex="-1">Un cliente su ECR + ECS <a class="header-anchor" href="#un-cliente-su-ecr-ecs" aria-label="Permalink to "Un cliente su ECR + ECS""></a></h2><p>Un cliente può scegliere ECR invece di GHCR, con un servizio ECS suo e il <code>.env</code> in un bucket S3 (ADR-0094 §1, ADR-0104). Lo strumento arriva col pacchetto: dalla radice del repo cliente, che porta la sua <code>deploy-ecr.conf</code>,</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --dry-run</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # solo i controlli</span></span>
|
|
12
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> exec</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> deploy-ecr</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">client</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --attendi</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # gate, build, push, CodePipeline</span></span></code></pre></div><p>L'immagine è la stessa di <code>image.yml</code> (o il Dockerfile del repo, se l'ha preso), con due tag su ECR: quello di deploy e quello di rilascio. La procedura completa, la <code>deploy-ecr.conf</code> e la creazione del servizio in <code>noeva-terraform</code> sono in <a href="./deploy-ecr">un cliente su ECR + ECS</a>.</p><h2 id="esecuzione" tabindex="-1">Esecuzione <a class="header-anchor" href="#esecuzione" aria-label="Permalink to "Esecuzione""></a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># una tantum: la tabella di destinazione deve esistere (DDL versionata nel repo cliente)</span></span>
|
|
11
13
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">imag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> list</span></span>
|
|
12
14
|
<span class="line"></span>
|
|
13
15
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env-file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .env</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">imag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><blockquote><p><strong>Pipeline incrementali:</strong> senza <code>--workspace</code> lo stato di pipeline è un file in <code>ETL_STATE_DIR</code> (default <code>.state/</code>), e il filesystem di un container <code>--rm</code> si perde a ogni run: la pipeline ripartirebbe sempre da <code>initial</code>. Usare <code>run <pipeline> --workspace <id></code> (stato su <code>noeva-server-api</code>, lo stesso del worker), oppure montare un volume scrivibile dall'utente del container su <code>ETL_STATE_DIR</code>. Vedi <a href="./stato-incrementale">stato incrementale</a>.</p></blockquote><p>Variabili richieste: quelle della pipeline, elencate nella sua <a href="./../pipelines/README">scheda</a> e in <code>.env.example</code>, più quelle del core (<a href="./../conventions/variabili-del-core">Variabili d'ambiente del core</a>). In produzione iniettarle da un <strong>secret manager</strong> (AWS Secrets Manager / SSM), non da <code>.env</code>.</p><h2 id="modelli-di-deploy-per-cliente" tabindex="-1">Modelli di deploy per cliente <a class="header-anchor" href="#modelli-di-deploy-per-cliente" aria-label="Permalink to "Modelli di deploy per cliente""></a></h2><p>Il servizio gira tipicamente sull'<strong>infra del cliente</strong>. L'immagine abilita i primi tre modelli; PM2 gira dai sorgenti, senza immagine:</p><table tabindex="0"><thead><tr><th>Modello</th><th>Come</th><th>Note</th></tr></thead><tbody><tr><td><strong>Gestito da noi</strong></td><td>Un servizio ECS per cliente con <code>etl serve</code>, definito in Terraform</td><td>Il job parte dallo scheduler di Noeva</td></tr><tr><td><strong>ECS del cliente</strong></td><td>Stessa immagine, task definition nel loro account</td><td>Solo accesso al registry + secrets del cliente</td></tr><tr><td><strong>Docker locale del cliente</strong></td><td><code>docker run</code> schedulato da cron sul loro host</td><td>Più semplice; idempotenza rende sicuri retry/sovrapposizioni</td></tr><tr><td><strong>PM2 dai sorgenti</strong></td><td><code>ecosystem()</code> del pacchetto: <code>etl serve</code> dal repo, senza build</td><td>Per un server Windows senza Docker</td></tr></tbody></table><h2 id="scheduling" tabindex="-1">Scheduling <a class="header-anchor" href="#scheduling" aria-label="Permalink to "Scheduling""></a></h2><p>La pipeline è <strong>idempotente</strong> (upsert/MERGE su chiave naturale): rieseguire o sovrapporre run non duplica dati. Quindi lo scheduler può essere semplice:</p><ul><li><strong>cron</strong> che lancia <code>docker run ... run <pipeline></code>;</li><li><strong>ECS Scheduled Task</strong> (cron via EventBridge);</li><li>per dipendenze/backfill complessi in futuro → orchestratore (es. Temporal TS).</li></ul><h2 id="networking" tabindex="-1">Networking <a class="header-anchor" href="#networking" aria-label="Permalink to "Networking""></a></h2><p>Il container deve raggiungere <strong>sorgente e sink</strong> (PG e SQL Server), che possono stare su host/VPC diversi. In locale, dai container verso DB sull'host: usare <code>host.docker.internal</code> come <code>*HOST</code>. In cloud: curare security group / routing verso entrambi i DB.</p><h2 id="osservabilita-—-il-report-di-run-e-il-risultato" tabindex="-1">Osservabilità — il report di run è il risultato <a class="header-anchor" href="#osservabilita-—-il-report-di-run-e-il-risultato" aria-label="Permalink to "Osservabilità — il report di run è il risultato""></a></h2><p>Il servizio è <strong>stateless</strong>: emette un <strong>report</strong> e termina (niente DB lato servizio).</p><ul><li><strong><code>stdout</code></strong> = il report in JSON (un oggetto). <strong><code>stderr</code></strong> = log umani.</li><li><strong>exit code</strong>: <code>0</code> se <code>success</code>/<code>partial</code>, <code>≠0</code> se <code>failed</code> (utile per alerting dello scheduler).</li><li>Anche in errore viene emesso un report <code>status: "failed"</code>.</li></ul><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># cattura il report e i log separatamente</span></span>
|
|
14
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"
|
|
15
|
-
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># archivialo dove vuoi (è il chiamante a deciderlo): file, S3, CloudWatch, ...</span></span></code></pre></div><p>Schema completo e semantica: <a href="./../conventions/run-report">docs/conventions/run-report.md</a>.</p>`,
|
|
16
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">docker</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --rm</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> --env-file</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> .env</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">imag</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">pipelin</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> ></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> report.json</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> 2></span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run.log</span></span>
|
|
17
|
+
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># archivialo dove vuoi (è il chiamante a deciderlo): file, S3, CloudWatch, ...</span></span></code></pre></div><p>Schema completo e semantica: <a href="./../conventions/run-report">docs/conventions/run-report.md</a>.</p>`,37)])])}const g=e(l,[["render",t]]);export{c as __pageData,g as default};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{_ as e,o as s,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const c=JSON.parse('{"title":"Runbook: distribuzione del runner ETL","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/deployment.md","filePath":"runbooks/deployment.md"}'),l={name:"runbooks/deployment.md"};function t(o,i,r,d,p,h){return s(),a("div",null,[...i[0]||(i[0]=[n("",37)])])}const g=e(l,[["render",t]]);export{c as __pageData,g as default};
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: server grafi etl serve (HTTP)","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/graph-server.md","filePath":"runbooks/graph-server.md"}'),o={name:"runbooks/graph-server.md"};function l(t,i,p,d,
|
|
1
|
+
import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: server grafi etl serve (HTTP)","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/graph-server.md","filePath":"runbooks/graph-server.md"}'),o={name:"runbooks/graph-server.md"};function l(t,i,p,r,d,c){return e(),a("div",null,[...i[0]||(i[0]=[n(`<h1 id="runbook-server-grafi-etl-serve-http" tabindex="-1">Runbook: server grafi <code>etl serve</code> (HTTP) <a class="header-anchor" href="#runbook-server-grafi-etl-serve-http" aria-label="Permalink to "Runbook: server grafi \`etl serve\` (HTTP)""></a></h1><h2 id="sintesi" tabindex="-1">Sintesi <a class="header-anchor" href="#sintesi" aria-label="Permalink to "Sintesi""></a></h2><ul><li><strong>Cosa fa:</strong> processo <strong>daemon</strong> che espone via HTTP la <strong>topologia dei grafi</strong> delle pipeline (nodi/archi, <code>PlanSpec</code>) e serve la documentazione già costruita su <code>/guida</code>. All'avvio calcola gli spec di tutte le pipeline del catalogo di <code>etl.config.ts</code> (via <code>getSpec()</code>) e li tiene in una <strong>cache in-memory immutabile</strong>; li serve poi read-only. I descriptor mostrano la configurazione <strong>reale</strong> del <code>.env</code> caricato, con la variabile e l'origine di ogni valore; un'istanza di connettore che non si costruisce ricade sull'esempio da sola, e le variabili mancanti sono marcate <code>mancante</code>. Nessuna pipeline ricade più sull'esempio per tutto il piano. <strong>Dopo una modifica al <code>.env</code> va riavviato</strong>: ogni piano porta l'ora in cui la cache è stata costruita (<code>computedAt</code>), così un riavvio mancato si vede. Sostituisce la generazione a build-time del vecchio <code>plans.generated.json</code> lato UI.</li><li><strong>Owner:</strong> team ETL.</li><li><strong>Consumatore:</strong> <code>noeva-etl-ui</code>, all'URL impostato nell'app (dialog «Server ETL»; predefinito <code>http://localhost:3005</code>).</li><li><strong>Criticità:</strong> bassa. Se è fermo, la UI non popola il selettore pipeline né il grafo (mostra lo stato di errore), ma nessun dato viene perso: al riavvio la cache viene ricostruita dal registro. Grafi e storico sono in sola lettura; l'unica scrittura è la run tracciata lanciata dalla UI (<code>POST /runs</code>, solo dal loopback), che scrive sui sink come una run normale e salva report e traccia nello storico locale <code>ETL_RUNS_DIR</code>.</li></ul><h2 id="esecuzione-normale" tabindex="-1">Esecuzione normale <a class="header-anchor" href="#esecuzione-normale" aria-label="Permalink to "Esecuzione normale""></a></h2><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">pnpm</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> run</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> etl:serve</span><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"> # oppure: pnpm run etl serve</span></span></code></pre></div><p>Nel container: <code>node dist/cli.js serve</code> (o l'equivalente entrypoint), con la porta esposta.</p><h3 id="endpoint" tabindex="-1">Endpoint <a class="header-anchor" href="#endpoint" aria-label="Permalink to "Endpoint""></a></h3><ul><li><p><code>GET /health</code> → <code>{ "status": "ok" }</code></p></li><li><p><code>GET /deploy</code> → chi è il deploy, per la UI desktop che vi si collega. Risponde <strong>senza autenticazione</strong>, perché serve a sapere dove fare il login, e porta solo dati non segreti: mai <code>NOEVA_API_KEY</code>.</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
|
|
2
2
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "client"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"acme"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
3
3
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "noevaApiBaseUrl"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"https://api.noeva.ai"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
|
|
4
4
|
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> "workspaces"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: [</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"<uuid-a>"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">"<uuid-b>"</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">],</span></span>
|
|
@@ -65,4 +65,4 @@ import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k
|
|
|
65
65
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> localhost:3005/graphs</span></span>
|
|
66
66
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> localhost:3005/graphs/orders-enriched-daily</span></span>
|
|
67
67
|
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -s</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> localhost:3005/sub-pipelines</span></span>
|
|
68
|
-
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -sI</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> localhost:3005/guida/</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> localhost:3005/guida/core/</span></span></code></pre></div><h2 id="diagnosi" tabindex="-1">Diagnosi <a class="header-anchor" href="#diagnosi" aria-label="Permalink to "Diagnosi""></a></h2><ul><li><strong>La UI non carica i grafi</strong> → verificare che il server sia su e raggiungibile (<code>curl</code> diretto isola server vs UI) e che l'URL nel dialog «Server ETL» dell'app punti all'host e alla porta giusti («Verifica connessione» fa lo stesso <code>GET /health</code>). Se la UI è su un altro PC, provare il <code>curl</code> <strong>da quel PC</strong> e controllare il firewall della macchina del server (porta <code>ETL_HTTP_PORT</code>).</li><li><strong>Grafi e storico ok, ma l'avanzamento live arriva a scatti</strong> → lo stream SSE (<code>EventSource</code>) è soggetto a CORS, a differenza delle altre richieste. <code>ETL_HTTP_CORS_ORIGIN</code> deve essere <code>*</code> oppure l'origine dell'app (<code>http://tauri.localhost</code> su Windows, <code>tauri://localhost</code> su macOS/Linux); altrimenti la UI ripiega sul polling.</li><li><strong>Il pannello mostra valori vecchi dopo una modifica al <code>.env</code></strong> → il server legge il <code>.env</code> una volta sola, all'avvio. Se l'ora di calcolo del piano (<code>computedAt</code> in <code>GET /graphs/:name</code>, in UTC) è precedente alla modifica, il server non è stato riavviato: riavviarlo e ricaricare il grafo.</li><li><strong><code>403</code> su <code>POST /runs</code> o su <code>/runs/:id/trace</code></strong> → la richiesta non arriva dalla macchina del server. Lancio e tracce rispondono solo dal loopback: l'app desktop deve girare sulla stessa macchina.</li><li><strong><code>503</code> sulle rotte <code>/runs</code></strong> → lo storico locale è spento (<code>ETL_RUNS_DIR=""</code>), quindi non c'è dove salvare report e tracce.</li><li><strong><code>404</code> su un grafo atteso</strong> → il nome non è nel catalogo di <code>etl.config.ts</code>, oppure <code>ETL_PIPELINE_WORKSPACES</code> non lo assegna a nessun workspace dell'istanza. Il log di avvio elenca le pipeline di ogni workspace; confrontare con <code>GET /graphs</code>.</li><li><strong><code>404</code> con «è una sub-pipeline»</strong> → il nome è quello di una sub-pipeline, che non ha un piano proprio: si legge in <code>GET /sub-pipelines</code>, e il suo grafo nel piano di una root che la istanzia (<code>usedBy</code>).</li><li><strong>Una sub-pipeline attesa manca da <code>/sub-pipelines</code></strong> → nessuna pipeline servita la istanzia: è visibile solo dove lo è una root che la usa.</li><li><strong>Nel log <code>Avviso: documentazione del cliente non costruita (…)</code></strong> → nella cartella fra parentesi non c'è il sito del cliente, e <code>/guida/</code> mostra la pagina che lo dice. Il sito si costruisce al deploy con <code>pnpm etl docs build</code> nel repo cliente, prima di riavviare <code>etl serve</code>, che guarda i siti solo all'avvio.</li><li><strong>Nel log <code>Avviso: guida del core non costruita (…)</code></strong> → <code>/guida/core/</code> risponde <code>404</code>. Nel pacchetto pubblicato la guida c'è sempre: l'avviso vuol dire un'installazione rotta, da reinstallare.</li><li><strong>L'avvio si ferma con «Due sub-pipeline diverse si chiamano …»</strong> → due root istanziano due definizioni diverse con lo stesso nome. Il test <code>src/sub-pipelines/list.test.ts</code> lo impedisce prima del rilascio; il nome va reso unico.</li></ul><h2 id="deploy" tabindex="-1">Deploy <a class="header-anchor" href="#deploy" aria-label="Permalink to "Deploy""></a></h2><p>Il server va deployato come <strong>servizio distinto</strong> dal <code>worker</code> (stesso codice/immagine, comando diverso), con la porta esposta. Aggiornare <code>Dockerfile</code
|
|
68
|
+
<span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">curl</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -sI</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> localhost:3005/guida/</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> localhost:3005/guida/core/</span></span></code></pre></div><h2 id="diagnosi" tabindex="-1">Diagnosi <a class="header-anchor" href="#diagnosi" aria-label="Permalink to "Diagnosi""></a></h2><ul><li><strong>La UI non carica i grafi</strong> → verificare che il server sia su e raggiungibile (<code>curl</code> diretto isola server vs UI) e che l'URL nel dialog «Server ETL» dell'app punti all'host e alla porta giusti («Verifica connessione» fa lo stesso <code>GET /health</code>). Se la UI è su un altro PC, provare il <code>curl</code> <strong>da quel PC</strong> e controllare il firewall della macchina del server (porta <code>ETL_HTTP_PORT</code>).</li><li><strong>Grafi e storico ok, ma l'avanzamento live arriva a scatti</strong> → lo stream SSE (<code>EventSource</code>) è soggetto a CORS, a differenza delle altre richieste. <code>ETL_HTTP_CORS_ORIGIN</code> deve essere <code>*</code> oppure l'origine dell'app (<code>http://tauri.localhost</code> su Windows, <code>tauri://localhost</code> su macOS/Linux); altrimenti la UI ripiega sul polling.</li><li><strong>Il pannello mostra valori vecchi dopo una modifica al <code>.env</code></strong> → il server legge il <code>.env</code> una volta sola, all'avvio. Se l'ora di calcolo del piano (<code>computedAt</code> in <code>GET /graphs/:name</code>, in UTC) è precedente alla modifica, il server non è stato riavviato: riavviarlo e ricaricare il grafo.</li><li><strong><code>403</code> su <code>POST /runs</code> o su <code>/runs/:id/trace</code></strong> → la richiesta non arriva dalla macchina del server. Lancio e tracce rispondono solo dal loopback: l'app desktop deve girare sulla stessa macchina.</li><li><strong><code>503</code> sulle rotte <code>/runs</code></strong> → lo storico locale è spento (<code>ETL_RUNS_DIR=""</code>), quindi non c'è dove salvare report e tracce.</li><li><strong><code>404</code> su un grafo atteso</strong> → il nome non è nel catalogo di <code>etl.config.ts</code>, oppure <code>ETL_PIPELINE_WORKSPACES</code> non lo assegna a nessun workspace dell'istanza. Il log di avvio elenca le pipeline di ogni workspace; confrontare con <code>GET /graphs</code>.</li><li><strong><code>404</code> con «è una sub-pipeline»</strong> → il nome è quello di una sub-pipeline, che non ha un piano proprio: si legge in <code>GET /sub-pipelines</code>, e il suo grafo nel piano di una root che la istanzia (<code>usedBy</code>).</li><li><strong>Una sub-pipeline attesa manca da <code>/sub-pipelines</code></strong> → nessuna pipeline servita la istanzia: è visibile solo dove lo è una root che la usa.</li><li><strong>Nel log <code>Avviso: documentazione del cliente non costruita (…)</code></strong> → nella cartella fra parentesi non c'è il sito del cliente, e <code>/guida/</code> mostra la pagina che lo dice. Il sito si costruisce al deploy con <code>pnpm etl docs build</code> nel repo cliente, prima di riavviare <code>etl serve</code>, che guarda i siti solo all'avvio.</li><li><strong>Nel log <code>Avviso: guida del core non costruita (…)</code></strong> → <code>/guida/core/</code> risponde <code>404</code>. Nel pacchetto pubblicato la guida c'è sempre: l'avviso vuol dire un'installazione rotta, da reinstallare.</li><li><strong>L'avvio si ferma con «Due sub-pipeline diverse si chiamano …»</strong> → due root istanziano due definizioni diverse con lo stesso nome. Il test <code>src/sub-pipelines/list.test.ts</code> lo impedisce prima del rilascio; il nome va reso unico.</li></ul><h2 id="deploy" tabindex="-1">Deploy <a class="header-anchor" href="#deploy" aria-label="Permalink to "Deploy""></a></h2><p>Il server va deployato come <strong>servizio distinto</strong> dal <code>worker</code> (stesso codice/immagine, comando diverso), con la porta esposta. Aggiornare di conseguenza il Dockerfile del pacchetto (<code>deploy/Dockerfile</code>) e, per ECR, <code>deploy/deploy-ecr.sh</code> (<a href="./deploy-ecr">runbook</a>).</p>`,30)])])}const E=s(o,[["render",l]]);export{k as __pageData,E as default};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: server grafi etl serve (HTTP)","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/graph-server.md","filePath":"runbooks/graph-server.md"}'),o={name:"runbooks/graph-server.md"};function l(t,i,p,d,
|
|
1
|
+
import{_ as s,o as e,c as a,a5 as n}from"./chunks/framework.qdetmeNX.js";const k=JSON.parse('{"title":"Runbook: server grafi etl serve (HTTP)","description":"","frontmatter":{},"headers":[],"relativePath":"runbooks/graph-server.md","filePath":"runbooks/graph-server.md"}'),o={name:"runbooks/graph-server.md"};function l(t,i,p,r,d,c){return e(),a("div",null,[...i[0]||(i[0]=[n("",30)])])}const E=s(o,[["render",l]]);export{k as __pageData,E as default};
|