Installation & Setup

Configura CodeCourier per lo sviluppo locale. Copre requisiti di sistema, variabili d'ambiente, configurazione di Convex, Clerk, E2B e Trigger.dev.

10 min letto
installationsetupenvironment

Questa guida copre tutto ciò di cui hai bisogno per far girare CodeCourier in locale per lo sviluppo. CodeCourier è un’applicazione Next.js supportata da Convex, Clerk, E2B e Trigger.dev. Ogni servizio richiede la propria configurazione, ma una volta impostato, l’esperienza di sviluppo locale è pienamente funzionante con hot reloading e dati in tempo reale.

Requisiti di sistema

  • Node.js - Versione 20.9.0 o successiva (richiesta dall’SDK Clerk)
  • Package manager - Bun (consigliato, usato negli script del progetto) oppure npm/yarn/pnpm
  • Git - Per clonare il repository e gestire i branch
  • Sistema operativo - macOS, Linux o Windows (con WSL consigliato per la migliore esperienza)

Bun è opzionale

Anche se il progetto è configurato per Bun (il nome del package è bun-nextjs-convex-clerk), funzionano anche tutti i comandi npm standard. Le istruzioni qui sotto mostrano entrambe le opzioni.

Clona e installa

1

Clona il repository

Terminal
git clone https://github.com/your-org/codecourier.git
cd codecourier
2

Installa le dipendenze

Terminal
bun install

Questo installa tutte le dipendenze di produzione e di sviluppo, inclusi Next.js, Convex, Clerk, l’SDK E2B, l’SDK Trigger.dev, Tailwind CSS, Radix UI, shadcn/ui, Framer Motion e gli strumenti di test (Vitest, Playwright).

Variabili d’ambiente

Crea un file .env.local nella root del progetto. Il repository include un file .env.example con tutte le variabili supportate. Copialo come punto di partenza:

Terminal
cp .env.example .env.local

Le seguenti variabili sono richieste per lo sviluppo locale:

Convex

.env.local
# Your Convex deployment URL (shown after running npx convex dev)
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud

# Convex site URL (used by Trigger.dev for HTTP callbacks)
CONVEX_SITE_URL=https://your-deployment.convex.site

Autenticazione Clerk

.env.local
# Clerk publishable key (client-side, starts with pk_test_ or pk_live_)
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx

# Clerk secret key (server-side, starts with sk_test_ or sk_live_)
CLERK_SECRET_KEY=sk_test_xxx

# Clerk JWT issuer domain (found in Clerk dashboard > JWT Templates)
CLERK_JWT_ISSUER_DOMAIN=https://your-clerk-domain.clerk.accounts.dev

# Clerk webhook signing secret (for Convex HTTP webhook handler)
CLERK_WEBHOOK_SECRET=whsec_xxx

Trigger.dev

.env.local
# Shared secret for authenticating callbacks between Trigger.dev and Convex
TRIGGER_CALLBACK_SECRET=your-random-secret-string

Genera un callback secret robusto

Il TRIGGER_CALLBACK_SECRET serve a verificare che le richieste HTTP in ingresso verso Convex provengano davvero dai tuoi job Trigger.dev. Usa una stringa crittograficamente casuale (almeno 32 caratteri). Puoi generarne una con openssl rand -hex 32.

Variabili opzionali

.env.local
# PostHog analytics (optional)
# NEXT_PUBLIC_POSTHOG_KEY=phc_xxx
# NEXT_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com

# Meta/Facebook Pixel (optional)
# NEXT_PUBLIC_META_PIXEL_ID=123456789

# Google Ads conversion tracking (optional)
# NEXT_PUBLIC_GOOGLE_ADS_ID=AW-123456789

Configurazione dei servizi

1

Imposta Convex

Convex è il database e il runtime backend di CodeCourier. Avvia il server di sviluppo Convex, che sincronizza il tuo schema e le tue function locali con un deployment di sviluppo:

Terminal
npx convex dev

Al primo avvio, la CLI Convex ti chiede di accedere e creare un nuovo progetto. Dopo la configurazione, stampa il tuo URL di deployment - copialo nel tuo .env.local come NEXT_PUBLIC_CONVEX_URL.

Il server di sviluppo Convex osserva le modifiche ai file nella directory convex/ e invia automaticamente gli aggiornamenti di schema e function. Tieni questo terminale in esecuzione durante lo sviluppo.

Variabili d'ambiente Convex

Il tuo deployment Convex ha bisogno anche di variabili d’ambiente per funzionalità come la verifica dei webhook Clerk. Impostale nel dashboard Convex sotto Settings > Environment Variables del tuo progetto. Come minimo, configura lì CLERK_WEBHOOK_SECRET e TRIGGER_CALLBACK_SECRET.
2

Configura l'autenticazione Clerk

Crea un’applicazione Clerk su dashboard.clerk.com:

  1. Crea una nuova applicazione e abilita i metodi di accesso desiderati (Google, GitHub, e-mail, ecc.)
  2. Copia la Publishable Key e la Secret Key dalla pagina API Keys nel tuo .env.local
  3. Configura un JWT Templateper Convex. Nel dashboard Clerk, vai in JWT Templates, crea un nuovo template chiamato “convex” e configura i campi issuer e audience come documentato nella guida di integrazione Convex + Clerk
  4. Copia il JWT issuer domain in CLERK_JWT_ISSUER_DOMAIN
  5. Configura un endpoint Webhook che punta al tuo Convex site URL (ad es., https://your-deployment.convex.site/clerk-webhook). Abilita gli eventi utente (user.created, user.updated, user.deleted). Copia il signing secret in CLERK_WEBHOOK_SECRET
3

Imposta l'accesso alle sandbox E2B

E2B fornisce le sandbox cloud in cui gli agenti IA vengono eseguiti. La configurazione avviene a livello di progetto nell’interfaccia CodeCourier (Project Settings > API Keys), non come variabile d’ambiente locale. Tuttavia, per verificare la tua configurazione E2B durante lo sviluppo:

  1. Crea un account su e2b.dev e ottieni la tua chiave API dal dashboard
  2. Dopo aver avviato CodeCourier, vai in Project Settings e aggiungi la tua chiave API E2B nella sezione API Keys

L’SDK E2B (package e2b) è già incluso nelle dipendenze del progetto. I sandbox template (che definiscono l’ambiente di base e gli strumenti preinstallati) sono configurati per workflow e gestiti tramite l’interfaccia CodeCourier.

4

Connetti Trigger.dev

Trigger.dev si occupa dell’esecuzione dei job in background per il provisioning delle sandbox, i run di workflow e le sessioni di issue. Per lo sviluppo locale:

  1. Registrati su trigger.dev e crea un nuovo progetto
  2. Installa la CLI Trigger.dev globalmente oppure usa npx:
Terminal
npx trigger.dev@latest dev

Questo avvia il server di sviluppo Trigger.dev, che si connette al cloud Trigger.dev per ricevere ed elaborare i job in locale. Il progetto include un file trigger.config.ts che definisce tutte le task registrate.

Trigger.dev è opzionale per lo sviluppo UI

Se stai lavorando solo sul frontend e non hai bisogno di testare l’esecuzione reale delle sandbox, puoi saltare la configurazione di Trigger.dev. L’interfaccia si caricherà comunque e mostrerà i dati da Convex - semplicemente i run e le sandbox non verranno eseguiti.

Avvia il server di sviluppo

Con Convex dev in esecuzione in un terminale, avvia il server di sviluppo Next.js in un altro:

Terminal
bun dev

L’applicazione si avvia su http://localhost:3000. Dovresti vedere la pagina di accesso Clerk. Dopo l’autenticazione, verrai indirizzato a creare il tuo primo progetto o a unirti a uno esistente.

Verifica l’installazione

Segui questa checklist per confermare che tutto funzioni:

  1. Autenticazione: Puoi accedere e disconnetterti tramite Clerk. Il tuo utente appare nel dashboard Convex sotto la tabella users.
  2. Creazione del progetto: Puoi creare un nuovo progetto. Controlla che le tabelle projects, projectMembers e projectSettings si popolino in Convex.
  3. Aggiornamenti in tempo reale: Apri due schede del browser sullo stesso progetto. Crea un workflow in una scheda e conferma che appaia istantaneamente nell’altra.
  4. Memorizzazione delle chiavi API: Aggiungi una chiave API E2B nelle impostazioni del progetto e verifica che appaia con solo gli ultimi quattro caratteri visibili.

Eseguire i test

CodeCourier include sia test unitari (Vitest) sia test end-to-end (Playwright):

Terminal
# Unit tests
npm run test

# Unit tests with watch mode
npm run test:watch

# Unit tests with coverage report
npm run test:coverage

# End-to-end tests (requires the dev server running)
npm run test:e2e

# E2E tests with interactive UI
npm run test:e2e:ui

Risoluzione dei problemi

Convex dev non si avvia

Assicurati di aver effettuato l’accesso alla CLI Convex ( npx convex login) e che il tuo file convex.json punti a un progetto valido. Se vedi errori di validazione dello schema, controlla che tutti i file nella directory convex/ compilino senza errori TypeScript.

Loop di reindirizzamento dell’autenticazione Clerk

Verifica che NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYcorrisponda all’ambiente della tua applicazione Clerk (test vs produzione). Assicurati che il JWT template in Clerk sia chiamato “convex” e che l’issuer domain in CLERK_JWT_ISSUER_DOMAIN corrisponda esattamente.

La creazione della sandbox fallisce

Controlla che la tua chiave API E2B sia configurata correttamente nelle impostazioni del progetto (non in .env.local - le chiavi E2B sono memorizzate per progetto in Convex). Verifica che il server di sviluppo Trigger.dev sia in esecuzione e connesso. Controlla il dashboard Trigger.dev per i log di esecuzione dei job.

Errori di type checking

Esegui il type checker per trovare i problemi:

Terminal
npm run typecheck

Il progetto usa TypeScript 5.9+ in modalità strict. Convex genera automaticamente i tipi in convex/_generated/ - se mancano, assicurati che npx convex dev sia stato eseguito almeno una volta.

Prossimi passi

Core Concepts

Comprendi il modello dei dati e come si collegano le funzionalità di CodeCourier.

Il tuo primo progetto

Percorso dettagliato della configurazione di un progetto per l'uso reale.