From 019b7e329885609a4954837e6f4f160f040a966f Mon Sep 17 00:00:00 2001 From: AdrianoDev Date: Wed, 29 Apr 2026 09:18:30 +0200 Subject: [PATCH] docs: README + DEPLOYMENT con stato CI/CD funzionante README aggiunge sezione 'CI/CD pipeline' che descrive i 5 job e i tag image. DEPLOYMENT espande sez. 1 con dettagli runner Gitea (network gitea_gitea-internal, image runner-images, label ubuntu-latest) e configurazione secret user-level REGISTRY_TOKEN con scope write:package. --- DEPLOYMENT.md | 47 ++++++++++++++++++++++++++++++++++++----------- README.md | 30 ++++++++++++++++++++++++------ 2 files changed, 60 insertions(+), 17 deletions(-) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 92032ae..af81d0a 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -23,19 +23,44 @@ Watchtower per il rollover automatico delle versioni. ## 1. Pipeline CI/CD (Gitea Actions) -`.gitea/workflows/ci.yml` ad ogni push su `main` esegue, in sequenza: +`.gitea/workflows/ci.yml` ad ogni push su `main` esegue 5 job: -1. **lint** (`ruff check`) — gating -2. **typecheck** (`mypy mcp_common`) — gating su mcp_common, warn-only sui servizi -3. **test** (`pytest services/`) — gating, 455 test -4. **build-and-push** — solo su push a `main`: - - Logga al registry `git.tielogic.xyz` con `secrets.GITEA_TOKEN` - - Builda `docker/base.Dockerfile` (cache) - - Builda e pusha `gateway` + 6 servizi MCP con tag: - - `:latest` (mobile, Watchtower polla questo) - - `:sha-XXXXXXX` (immutabile, per rollback puntuali) +1. **lint** (`ruff check services/`) — gating, 0 violations. +2. **typecheck** (`mypy services/common/src/mcp_common`) — gating sul + modulo comune, warn-only sui servizi. +3. **test** (`pytest services/`) — gating, 478 test verdi. +4. **validate-config** — `docker compose config -q` su `docker-compose.yml` + e `docker-compose.prod.yml` + `caddy validate --config Caddyfile`. +5. **build-and-push** — solo su push a `main` (skip su PR): + - `docker login git.tielogic.xyz` con `${{ secrets.REGISTRY_TOKEN }}` + (PAT scope `write:package`, configurato user-level su Gitea). + - Builda e pusha **8 image** al registry con tag `:latest` + `:sha-X`: + - `git.tielogic.xyz/adriano/cerbero-mcp/base` + - `git.tielogic.xyz/adriano/cerbero-mcp/gateway` + - `git.tielogic.xyz/adriano/cerbero-mcp/mcp-{deribit,bybit,hyperliquid,alpaca,macro,sentiment}` + - Cache Docker buildx via registry stesso (`buildcache:` per ognuna) + → run successivi 5-10× più veloci. -Le PR fanno girare solo lint+typecheck+test, niente build/push. +Le PR fanno girare solo `lint`+`typecheck`+`test`+`validate-config`, +niente build/push (gating per merge). + +### Setup runner Gitea + +Il runner act_runner deve girare: +- Sulla stessa Docker network di Gitea (`gitea_gitea-internal` o equivalente) + altrimenti `actions/checkout@v4` non risolve `gitea:3000` per il clone. +- Con bind di `/var/run/docker.sock` per buildare image dai workflow. +- Image dei job mappata a `docker.gitea.com/runner-images:ubuntu-22.04` + (default Gitea, contiene docker CLI + buildx + git + curl + node). +- Label: almeno `ubuntu-latest` (usato dal workflow). Altre label + (`tielogic-ci`, `ubuntu-22.04`, ecc.) opzionali. + +### Setup secret REGISTRY_TOKEN + +Crea un Personal Access Token Gitea con scope `write:package` (User +Settings → Applications → Generate Token). Aggiungilo come secret a +livello user (User Settings → Secrets → New Secret) con nome +`REGISTRY_TOKEN`. Tutti i tuoi repo ereditano il secret automaticamente. ## 2. Setup iniziale del VPS diff --git a/README.md b/README.md index cb82ab1..32bf47f 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,29 @@ OI history. **Nuovi**: `get_funding_arb_spread` (opportunità arb compatte), `get_liquidation_heatmap` (heuristic da OI delta + funding extreme), `get_cointegration_pairs` (Engle-Granger su coppie crypto). -## Avvio locale +## CI/CD pipeline + +Pipeline Gitea Actions in `.gitea/workflows/ci.yml` esegue ad ogni push +su `main`: + +1. **lint** — `ruff check services/` +2. **typecheck** — `mypy mcp_common` (gating) + servizi (warn-only) +3. **test** — `pytest services/` (478 test) +4. **validate-config** — sintassi compose + Caddyfile +5. **build-and-push** — solo su `main`: builda e pusha 8 image al + container registry Gitea (`git.tielogic.xyz/adriano/cerbero-mcp/*`) + con tag `:latest` + `:sha-XXXXXXX` per rollback puntuali. + +Le PR fanno girare solo i 4 job di gating (lint/test/validate). Il job +`build-and-push` è skippato. + +Sul VPS produzione, **Watchtower** polla il registry ogni 5 min e +auto-aggiorna i container quando il digest del tag `:latest` cambia. + +Vedi [`DEPLOYMENT.md`](DEPLOYMENT.md) per setup runner, secret +`REGISTRY_TOKEN`, deploy VPS, smoke test, rollback. + +## Avvio locale (dev) ```bash docker compose up -d @@ -67,11 +89,7 @@ Vedi `secrets/*.json` e variabili `*_TESTNET` / `ALPACA_PAPER` in ### Deploy su VPS pubblica (`cerbero-mcp.tielogic.xyz`) -Vedi [`DEPLOYMENT.md`](DEPLOYMENT.md) per la guida completa: pipeline CI/CD -(Gitea Actions → registry → Watchtower auto-update), setup VPS step-by-step, -rollback, smoke test post-deploy. - - +Vedi [`DEPLOYMENT.md`](DEPLOYMENT.md) per il runbook completo end-to-end. Il gateway Caddy è configurato per: - TLS automatico via Let's Encrypt (richiede DNS A/AAAA che punti al