CS Platform Wiki

Avvio stack in localhost ​

Questa guida descrive il percorso canonico per eseguire l'intero stack locale del workspace cs-repository.

Il bootstrap parte sempre da platform-local-stack. I singoli repository possono essere avviati da soli solo per debug puntuale, non come entrypoint principale.

Nei comandi sotto, sostituisci <workspace-root> con la directory locale che contiene i repository sibling del workspace.

Prerequisiti ​

  • Node.js >= 22
  • npm >= 10
  • Docker Desktop attivo

Verifica rapida:

bash
node -v
npm -v
docker info

Setup una tantum ​

Installa le dipendenze in tutti i repository eseguibili del workspace:

bash
cd <workspace-root>/platform-auth-service && npm install
cd <workspace-root>/platform-ai-service && npm install
cd <workspace-root>/platform-scraper-service && npm install
cd <workspace-root>/platform-payments-service && npm install
cd <workspace-root>/platform-connectors-service && npm install
cd <workspace-root>/platform-mcp-service && npm install
cd <workspace-root>/platform-agent-service && npm install
cd <workspace-root>/platform-local-stack && npm install
cd <workspace-root>/platform-status-service && npm install
cd <workspace-root>/platform-wiki && npm install
cd <workspace-root>/cs-portal && npm install
cd <workspace-root>/cs-chat && npm install
cd <workspace-root>/cs-transacion-manage && npm install
cd <workspace-root>/cs-tools && npm install
cd <workspace-root>/sfdc-external && npm install
cd <workspace-root>/funnel-ia-engine && npm install

Preparazione environment ​

funnel-ia-engine ​

Prepara i file .env del repo e dei workspace:

bash
cd <workspace-root>/funnel-ia-engine
cp .env.example .env
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

Note operative:

  • in frontend/.env lascia VITE_API_BASE_URL vuota per usare lo stesso origin browser con prefisso /api
  • in backend/.env PLATFORM_AI_SERVICE_URL punta di default a http://localhost:3300
  • il backend Funnel bootstrapa di default le credenziali locali admin@local.test / ChangeMe123! dentro platform-auth-service

platform-ai-service ​

Prepara il file .env del servizio:

bash
cd <workspace-root>/platform-ai-service
cp .env.example .env

Valori locali gia allineati nel template:

  • PORT=3300
  • PLATFORM_INTERNAL_TOKEN=platform-local-stack-internal-token
  • AI_DATABASE_URL

La configurazione dei provider AI viene letta dallo state store PostgreSQL. Per test locali senza provider esterni usa il provider template tramite le route admin/backoffice o un seed gia presente nel database locale.

platform-mcp-service ​

Per il bootstrap canonico via platform-local-stack non serve copiare env manualmente. Se lo avvii standalone, allinea almeno:

  • PORT=3500
  • PLATFORM_INTERNAL_TOKEN=platform-local-stack-internal-token
  • PLATFORM_AUTH_SERVICE_URL=http://127.0.0.1:3100
  • PLATFORM_AI_SERVICE_URL=http://127.0.0.1:3300
  • PLATFORM_CONNECTORS_SERVICE_URL=http://127.0.0.1:3200
  • PLATFORM_STATUS_SERVICE_URL=http://127.0.0.1:3400

platform-agent-service ​

Per il bootstrap canonico via platform-local-stack, il launcher passa DATABASE_URL, REDIS_URL, PLATFORM_MCP_SERVICE_URL e PLATFORM_INTERNAL_TOKEN. Se lo avvii standalone, usa il database agent-postgres e Redis del local stack.

platform-scraper-service ​

Per il bootstrap canonico via platform-local-stack, il launcher passa SCRAPER_DATABASE_URL, REDIS_URL e PLATFORM_INTERNAL_TOKEN. Se lo avvii standalone, usa il database scraper-postgres; la configurazione provider viene persistita in Postgres mentre Redis resta dedicato alla coda e allo stato crawl.

cs-portal ​

Prepara gli env se devi avviare il repo fuori dal local stack:

bash
cd <workspace-root>/cs-portal
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

Verifica almeno:

  • SESSION_COOKIE_*
  • PLATFORM_CONNECTORS_SERVICE_URL
  • PLATFORM_INTERNAL_TOKEN
  • DEFAULT_DATA_SOURCE_ID
  • VITE_API_BASE_URL=/api
  • Per il confronto Commesse/Google Sheets: GOOGLE_COMMESSE_SPREADSHEET_ID, GOOGLE_COMMESSE_SHEET_MAX_ROWS e una service account con accesso Viewer al workbook; abilita anche sheets.googleapis.com nel relativo progetto Google. Il browser continua a usare soltanto /api/administration/commesse/*.
  • CS_PORTAL_LOCAL_PASSWORD_LOGIN_ENABLED=true in backend/.env e frontend/.env se vuoi mostrare il form email/password locale fuori dal local stack. Nel local stack il valore è centralizzato in platform-local-stack/config/stack-paths.json localEnv. Se non esiste ancora una credenziale locale cs-portal, la login page mostra il wizard di prima utenza collegato a un Contact Salesforce attivo.

cs-chat ​

Prepara gli env se devi avviare il repo fuori dal local stack:

bash
cd <workspace-root>/cs-chat
cp .env.example .env

Verifica almeno:

  • DATABASE_URL
  • PLATFORM_AUTH_SERVICE_URL
  • PLATFORM_AI_SERVICE_URL
  • PLATFORM_AGENT_SERVICE_URL
  • PLATFORM_MCP_SERVICE_URL
  • PLATFORM_INTERNAL_TOKEN
  • CS_CHAT_AGENT_CALLBACK_BASE_URL
  • CS_CHAT_PRODUCT_CODE=cs-chat
  • CS_CHAT_MCP_MAX_STEPS=8

cs-transacion-manage ​

Prepara gli env se devi avviare il repo fuori dal local stack:

bash
cd <workspace-root>/cs-transacion-manage
cp apps/api/.env.example apps/api/.env

Verifica almeno:

  • DATABASE_URL
  • PLATFORM_AUTH_SERVICE_URL
  • PLATFORM_PAYMENTS_SERVICE_URL
  • PLATFORM_INTERNAL_TOKEN
  • CS_TRANSACTION_PRODUCT_CODE=cs-transacion-manage
  • PORT

cs-tools ​

Prepara gli env se devi avviare il repo fuori dal local stack:

bash
cd <workspace-root>/cs-tools
cp apps/api/.env.example apps/api/.env

Verifica almeno:

  • DATABASE_URL
  • PLATFORM_AUTH_SERVICE_URL
  • PLATFORM_INTERNAL_TOKEN
  • CS_TOOLS_PRODUCT_CODE=cs-tools
  • WEB_ORIGIN
  • SESSION_COOKIE_DOMAIN
  • PORT

sfdc-external ​

Per sfdc-external non c'è oggi un passaggio canonico cp ... .env già documentato al livello root del repo.

Usa backend/.env.example come sorgente di riferimento per allineare le variabili richieste dal tuo ambiente locale:

bash
cd <workspace-root>/sfdc-external
sed -n '1,220p' backend/.env.example
sed -n '1,120p' frontend/.env.example

In particolare verifica almeno:

  • DATABASE_URL
  • SHADOW_DATABASE_URL
  • FRONTEND_ORIGINS
  • eventuali variabili auth o Salesforce richieste dal tuo scenario locale

Per il frontend, il default locale resta VITE_API_BASE_URL=/api.

Servizi senza setup .env dedicato ​

Per il bootstrap canonico via platform-local-stack, platform-auth-service, platform-connectors-service, platform-mcp-service, platform-agent-service, platform-status-service e platform-wiki non richiedono copie manuali di file .env: lo stack launcher passa le variabili runtime necessarie, incluso DATABASE_URL per il catalogo prodotti status.

Allineamento database locali ​

sfdc-external ​

Genera il client Prisma ed esegui le migrazioni:

bash
cd <workspace-root>/sfdc-external
npm exec --workspace backend prisma -- generate --schema prisma/schema.prisma
npm exec --workspace backend prisma -- migrate dev --schema prisma/schema.prisma

funnel-ia-engine ​

Allinea Prisma nel backend:

bash
cd <workspace-root>/funnel-ia-engine/backend
npm run prisma:generate
npm run prisma:migrate:deploy

platform-auth-service ​

Non richiede migrazioni manuali. All'avvio inizializza la propria tabella di stato nel database auth-postgres.

platform-agent-service ​

Se avvii il servizio fuori dal local stack, genera Prisma e applica le migrazioni con DATABASE_URL puntato al database agent-postgres:

bash
cd <workspace-root>/platform-agent-service
npm run prisma:generate
npm run prisma:migrate:deploy

platform-status-service ​

Se avvii il servizio fuori dal local stack, genera Prisma e applica le migrazioni con DATABASE_URL puntato al database status scelto:

bash
cd <workspace-root>/platform-status-service
npm run prisma:generate --workspace backend
npm run prisma:migrate:deploy --workspace backend

cs-chat ​

Genera il client Prisma ed esegui le migrazioni:

bash
cd <workspace-root>/cs-chat
npm run prisma:generate
npm run prisma:migrate:dev

cs-transacion-manage ​

Se avvii il repo fuori dal local stack, genera il client Prisma ed esegui le migrazioni:

bash
cd <workspace-root>/cs-transacion-manage
npm run db:migrate

cs-tools ​

Se avvii il repo fuori dal local stack, genera il client Prisma ed esegui le migrazioni:

bash
cd <workspace-root>/cs-tools
npm run prisma:generate -w apps/api
npm run prisma:migrate:deploy -w apps/api

Avvio canonico dell'intero stack ​

L'unico entrypoint locale canonico è platform-local-stack:

bash
cd <workspace-root>/platform-local-stack
npm run check-paths
npm run profiles
npm run start:dev

npm run check-paths risolve i repository sibling dal basename del remote origin, con fallback ai nomi directory storici definiti in platform-local-stack/config/stack-paths.json. Se il workspace root non coincide con la parent directory di platform-local-stack, esporta STACK_WORKSPACE_ROOT prima di lanciare i comandi.

I backend Nest vengono avviati dal local stack tramite lo script start:local-stack, che è l'entrypoint watch esplicito per il bootstrap locale (nest start --watch). Per avvii standalone usa i normali script start o start:prod del repo. Ogni backend Nest deve mantenere compilerOptions.deleteOutDir: true in nest-cli.json e disabilitare l'incremental cache in tsconfig.build.json, così dist viene pulita prima di emettere output build/watch e non rimangono layout o metadati generati obsoleti.

npm run start:dev avvia anche il processo watchdog, che controlla i processi host-managed tracciati in .runtime/pids.json e riavvia un servizio se il watcher dev esce dopo cambi schema, build o runtime. Per i servizi con health locale configurata, il watchdog verifica anche l'HTTP runtime e riavvia il servizio quando il watcher resta vivo ma l'applicazione non risponde per piu probe consecutivi. Questo copre i rebuild Nest in cui nest start --watch continua a girare, ma il processo applicativo figlio e morto. Quando fermi intenzionalmente un servizio con npm run stop:dev -- <service>, il servizio viene rimosso dal tracking prima dello stop e il watchdog non lo riavvia.

npm run start:dev usa il profilo YAML full come default e avvia:

  • PostgreSQL per platform-auth-service
  • PostgreSQL per platform-agent-service
  • PostgreSQL per platform-payments-service
  • PostgreSQL per platform-scraper-service
  • PostgreSQL per sfdc-external
  • PostgreSQL e Redis per funnel-ia-engine
  • PostgreSQL per cs-chat
  • PostgreSQL per cs-transacion-manage
  • PostgreSQL per cs-tools
  • pgAdmin
  • Loki, Grafana e Promtail
  • platform-auth-service
  • platform-ai-service
  • platform-scraper-service
  • platform-payments-service
  • platform-mcp-service
  • platform-agent-service
  • platform-connectors-service
  • platform-status-service/backend
  • sfdc-external/backend
  • funnel-ia-engine/backend
  • cs-portal/backend
  • cs-chat/apps/api
  • cs-transacion-manage/packages/shared
  • cs-transacion-manage/apps/api
  • cs-tools/apps/api
  • platform-status-service/frontend
  • sfdc-external/frontend
  • funnel-ia-engine/frontend
  • cs-portal/frontend
  • cs-chat/apps/web
  • cs-transacion-manage/apps/web
  • cs-tools/apps/web
  • funnel-ia-engine/backend worker
  • platform-wiki
  • reverse proxy locale su porta 8080

I profili disponibili sono definiti in platform-local-stack/config/profiles e possono essere ispezionati con:

bash
cd <workspace-root>/platform-local-stack
npm run profiles

URL locali ​

Host canonici via proxy ​

  • http://auth.cs.lvh.me:8080
  • http://ai.cs.lvh.me:8080
  • http://agent.cs.lvh.me:8080
  • http://scraper.cs.lvh.me:8080
  • http://payments.cs.lvh.me:8080
  • http://mcp.cs.lvh.me:8080/mcp
  • http://wiki.cs.lvh.me:8080
  • http://status.cs.lvh.me:8080
  • http://status.cs.lvh.me:8080/api/status/overview
  • http://pgadmin.cs.lvh.me:8080
  • http://grafana.cs.lvh.me:8080
  • http://loki.cs.lvh.me:8080
  • http://promtail.cs.lvh.me:8080
  • http://sfdc.cs.lvh.me:8080
  • http://funnel.cs.lvh.me:8080
  • http://portal.cs.lvh.me:8080
  • http://chat.cs.lvh.me:8080
  • http://transactions.cs.lvh.me:8080
  • http://tools.cs.lvh.me:8080

Endpoint diretti utili ​

  • http://127.0.0.1:3100/health per platform-auth-service
  • http://127.0.0.1:3200/health per platform-connectors-service
  • http://127.0.0.1:3300/health per platform-ai-service
  • http://127.0.0.1:3400/health per platform-status-service/backend
  • http://127.0.0.1:3400/api/status/overview per il payload aggregato di platform-status-service
  • http://127.0.0.1:3500/health per platform-mcp-service
  • http://127.0.0.1:3600/health per platform-agent-service
  • http://127.0.0.1:3700/health per platform-payments-service
  • http://127.0.0.1:3800/health per platform-scraper-service
  • http://127.0.0.1:3003/api/health per cs-portal/backend
  • http://127.0.0.1:3004/api/health per cs-chat/apps/api
  • http://127.0.0.1:3005/api/health per cs-transacion-manage/apps/api
  • http://127.0.0.1:3006/api/health per cs-tools/apps/api
  • http://127.0.0.1:5176 per platform-status-service/frontend
  • http://127.0.0.1:5177 per cs-portal/frontend
  • http://127.0.0.1:5178 per cs-chat/apps/web
  • http://127.0.0.1:5179 per cs-transacion-manage/apps/web
  • http://127.0.0.1:5180 per cs-tools/apps/web
  • http://127.0.0.1:5050 per pgAdmin
  • http://127.0.0.1:3002 per Grafana
  • http://127.0.0.1:3101 per Loki
  • http://127.0.0.1:9080 per Promtail

Per status.cs.lvh.me, sfdc.cs.lvh.me, funnel.cs.lvh.me, portal.cs.lvh.me, chat.cs.lvh.me, transactions.cs.lvh.me e tools.cs.lvh.me il proxy serve il frontend sull'host root e inoltra il backend solo sui path /api/* (piu /socket.io per Funnel).

lvh.me punta già a 127.0.0.1, quindi non serve modificare /etc/hosts.

Verifiche rapide post-avvio ​

Verifica UI e routing ​

Apri questi URL e controlla che rispondano correttamente:

  • http://wiki.cs.lvh.me:8080
  • http://status.cs.lvh.me:8080
  • http://funnel.cs.lvh.me:8080
  • http://sfdc.cs.lvh.me:8080
  • http://portal.cs.lvh.me:8080
  • http://chat.cs.lvh.me:8080
  • http://transactions.cs.lvh.me:8080
  • http://tools.cs.lvh.me:8080
  • http://auth.cs.lvh.me:8080
  • http://ai.cs.lvh.me:8080
  • http://mcp.cs.lvh.me:8080/mcp

Verifica servizi tecnici ​

  • pgAdmin: http://pgadmin.cs.lvh.me:8080 credenziali: pgadmin@example.com / pgadmin
  • Grafana: http://grafana.cs.lvh.me:8080 credenziali: admin / admin su volume nuovo; se il volume esiste già mantiene la password inizializzata in precedenza

pgAdmin pre-registra i database locali:

  • Auth Postgres
  • Agent Postgres
  • Payments Postgres
  • Scraper Postgres
  • SFDC Postgres
  • Funnel Postgres
  • CS Chat Postgres
  • Transaction Manage Postgres
  • CS Tools Postgres

Password locali alla prima connessione:

  • Auth Postgres: platform_auth / platform_auth
  • Agent Postgres: platform_agent / platform_agent
  • Payments Postgres: platform_payments / platform_payments
  • Scraper Postgres: platform_scraper / platform_scraper
  • SFDC Postgres: app_rw / app_rw
  • Funnel Postgres: funnelia / funnelia
  • CS Chat Postgres: cs_chat / cs_chat
  • Transaction Manage Postgres: postgres / postgres
  • CS Tools Postgres: postgres / postgres

Verifica status dashboard ​

  • UI: http://status.cs.lvh.me:8080
  • sessione/setup: http://status.cs.lvh.me:8080/api/status-auth/session
  • overview aggregata: http://status.cs.lvh.me:8080/api/status/overview
  • health backend diretto: http://127.0.0.1:3400/health

platform-status-service è l'aggregatore canonico dello stato runtime dei microservizi. Il catalogo /products persiste prodotti, health target e link via Prisma nelle tabelle status_* sul database locale condiviso auth-postgres. La prima apertura della UI mostra il setup se non esiste una membership cs-status con ruolo SUPER_ADMIN.

Verifica health endpoints ​

Esempi di check rapidi:

bash
curl http://auth.cs.lvh.me:8080/health
curl http://ai.cs.lvh.me:8080/health
curl http://scraper.cs.lvh.me:8080/health
curl http://payments.cs.lvh.me:8080/health
curl http://127.0.0.1:3200/health
curl http://127.0.0.1:3500/health
curl http://127.0.0.1:3600/health
curl http://127.0.0.1:3000/api/health
curl http://127.0.0.1:3001/api/health
curl http://127.0.0.1:3003/api/health
curl http://127.0.0.1:3005/api/health
curl http://127.0.0.1:3006/api/health
curl http://127.0.0.1:3400/health
curl http://status.cs.lvh.me:8080/api/status/overview

Verifica auth condivisa ​

Per verificare la sessione condivisa tra prodotti:

  1. Apri http://funnel.cs.lvh.me:8080/#/login
  2. Esegui login con admin@local.test / ChangeMe123!
  3. Verifica GET http://funnel.cs.lvh.me:8080/api/auth/session
  4. Apri http://sfdc.cs.lvh.me:8080 senza rifare login

Check API rapido:

bash
curl -X POST http://funnel.cs.lvh.me:8080/api/auth/login/password \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@local.test","password":"ChangeMe123!"}'

Se stai verificando platform-auth-service in isolamento, ricorda che quelle credenziali non esistono finche un backend di prodotto non le sincronizza oppure finche non fai bootstrap via /internal/identities/upsert.

Comandi utili ​

Stato servizi ​

bash
cd <workspace-root>/platform-local-stack
npm run status

Il comando mostra sia lo stato del processo sia la health configurata. Un watcher vivo con app non raggiungibile viene quindi mostrato come RUNNING ... health=down, non come servizio sano.

Stop completo ​

bash
cd <workspace-root>/platform-local-stack
npm run stop:dev

Avvio di un sottoinsieme esplicito ​

Per un setup minimo con servizi CORE e status dashboard:

bash
cd <workspace-root>/platform-local-stack
npm run start:dev -- auth ai connectors mcp statusBackend statusFrontend proxy

Avvio tramite profilo ​

bash
cd <workspace-root>/platform-local-stack
npm run start:dev -- --profile sfdc

Solo status dashboard, incluso auth per setup/login:

bash
cd <workspace-root>/platform-local-stack
npm run start:dev -- --profile status

Solo MCP e dipendenze core:

bash
cd <workspace-root>/platform-local-stack
npm run start:dev -- --profile mcp

Solo CS Chat e dipendenze core, incluso Agent per le risposte MCP reali:

bash
cd <workspace-root>/platform-local-stack
npm run start:dev -- --profile chat

Solo CS Transaction Manage, incluso Payments per il tier subscription usato dall'ACL prodotto:

bash
cd <workspace-root>/platform-local-stack
npm run start:dev -- --profile transactions

Solo CS Tools, incluso Auth per login/sessione condivisa:

bash
cd <workspace-root>/platform-local-stack
npm run start:dev -- --profile tools

Solo CS Portal:

bash
cd <workspace-root>/platform-local-stack
npm run start:dev -- --profile portal

Il local stack abilita il login locale email/password di CS Portal tramite config/stack-paths.json localEnv. Per cambiare temporaneamente il valore puoi sovrascriverlo da shell:

bash
cd <workspace-root>/platform-local-stack
CS_PORTAL_LOCAL_PASSWORD_LOGIN_ENABLED=true npm run start:dev -- --profile portal

Composizione di più profili ​

bash
cd <workspace-root>/platform-local-stack
npm run start:dev -- --profile core --profile wiki

Dry run della risoluzione ​

bash
cd <workspace-root>/platform-local-stack
npm run start:dev -- --profile funnel --dry-run

Log runtime ​

I log runtime locali finiscono in:

  • <workspace-root>/platform-local-stack/.runtime/logs

Promtail raccoglie questi file e li invia a Loki, oltre ai log dei container Docker del local stack e dei processi host-managed come auth, ai, agent, connectors, mcp, sfdcBackend, funnelBackend, portalBackend, chatBackend, transactionShared, transactionBackend, toolsBackend, statusBackend, sfdcFrontend, funnelFrontend, portalFrontend, chatFrontend, transactionFrontend, toolsFrontend, statusFrontend, wiki e proxy.

Troubleshooting minimo ​

Porte occupate ​

Se una porta è già occupata il bootstrap può fallire. Le porte usate dal local stack sono:

  • 8080
  • 3100
  • 3101
  • 3200
  • 3300
  • 3400
  • 3500
  • 3600
  • 3000
  • 3001
  • 3002
  • 3003
  • 3004
  • 3005
  • 3006
  • 5050
  • 5173
  • 5174
  • 5175
  • 5176
  • 5177
  • 5178
  • 5179
  • 5180
  • 5432
  • 5433
  • 5434
  • 5435
  • 5436
  • 5437
  • 5438
  • 5440
  • 6379
  • 9080

lvh.me ​

lvh.me risolve già verso 127.0.0.1. Se i domini *.cs.lvh.me non rispondono, il problema è quasi sempre nel bootstrap locale o nel reverse proxy, non nella risoluzione DNS.

Bootstrap canonico unico ​

  • usa platform-local-stack come entrypoint locale principale
  • usa i comandi repo-locali solo per debug puntuale
  • se npm run check-paths fallisce, correggi prima i path del workspace e poi rilancia lo stack

Workspace reference: /Users/jeanpaul/projects/cs-repository

Internal documentation scaffold