Installation & Setup

Richten Sie CodeCourier für die lokale Entwicklung ein. Behandelt Systemanforderungen, Umgebungsvariablen sowie die Konfiguration von Convex, Clerk, E2B und Trigger.dev.

10 min Lesezeit
installationsetupenvironment

Diese Anleitung deckt alles ab, was Sie benötigen, um CodeCourier lokal für die Entwicklung auszuführen. CodeCourier ist eine Next.js-Anwendung, die von Convex, Clerk, E2B und Trigger.dev unterstützt wird. Jeder Dienst benötigt seine eigene Konfiguration, aber einmal eingerichtet ist die lokale Entwicklungserfahrung mit Hot Reloading und Echtzeit-Daten voll funktionsfähig.

Systemanforderungen

  • Node.js - Version 20.9.0 oder neuer (vom Clerk-SDK gefordert)
  • Paketmanager - Bun (empfohlen, in den Projekt-Scripts verwendet) oder npm/yarn/pnpm
  • Git - Zum Klonen des Repositories und Verwalten von Branches
  • Betriebssystem - macOS, Linux oder Windows (mit WSL für die beste Erfahrung empfohlen)

Bun ist optional

Während das Projekt für Bun konfiguriert ist (der Paketname ist bun-nextjs-convex-clerk), funktionieren auch alle standardmäßigen npm-Befehle. Die folgenden Anweisungen zeigen beide Optionen.

Klonen und installieren

1

Repository klonen

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

Abhängigkeiten installieren

Terminal
bun install

Dies installiert alle Produktions- und Entwicklungs-Abhängigkeiten einschließlich Next.js, Convex, Clerk, dem E2B-SDK, Trigger.dev-SDK, Tailwind CSS, Radix UI, shadcn/ui, Framer Motion sowie Test-Tools (Vitest, Playwright).

Umgebungsvariablen

Erstellen Sie eine Datei .env.local im Projekt-Root. Das Repository enthält eine Datei .env.example mit allen unterstützten Variablen. Kopieren Sie sie als Ausgangspunkt:

Terminal
cp .env.example .env.local

Die folgenden Variablen sind für die lokale Entwicklung erforderlich:

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

Clerk-Authentifizierung

.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

Starkes Callback-Secret generieren

Das TRIGGER_CALLBACK_SECRET wird verwendet, um zu überprüfen, dass eingehende HTTP-Anfragen an Convex tatsächlich von Ihren Trigger.dev-Jobs stammen. Verwenden Sie eine kryptografisch zufällige Zeichenkette (mindestens 32 Zeichen). Sie können eine mit openssl rand -hex 32 generieren.

Optionale Variablen

.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

Dienst-Einrichtung

1

Convex einrichten

Convex ist die Datenbank und Backend-Runtime für CodeCourier. Starten Sie den Convex-Entwicklungsserver, der Ihr lokales Schema und Ihre Funktionen mit einer Entwicklungs-Deployment synchronisiert:

Terminal
npx convex dev

Beim ersten Lauf fordert Sie die Convex-CLI zum Einloggen auf und erstellt ein neues Projekt. Nach dem Setup gibt sie Ihre Deployment-URL aus - kopieren Sie diese in Ihre .env.local als NEXT_PUBLIC_CONVEX_URL.

Der Convex-Dev-Server überwacht Änderungen an Dateien im Verzeichnis convex/ und pusht automatisch Schema- und Funktions-Updates. Lassen Sie dieses Terminal während der Entwicklung laufen.

Convex-Umgebungsvariablen

Ihr Convex-Deployment benötigt ebenfalls Umgebungsvariablen für Funktionen wie die Clerk-Webhook-Verifizierung. Setzen Sie sie im Convex-Dashboard unter den Settings > Environment Variables Ihres Projekts. Konfigurieren Sie mindestens CLERK_WEBHOOK_SECRET und TRIGGER_CALLBACK_SECRET dort.
2

Clerk-Authentifizierung konfigurieren

Erstellen Sie eine Clerk-Anwendung unter dashboard.clerk.com:

  1. Erstellen Sie eine neue Anwendung und aktivieren Sie die gewünschten Anmeldemethoden (Google, GitHub, E-Mail usw.)
  2. Kopieren Sie den Publishable Key und den Secret Key von der API-Keys-Seite in Ihre .env.local
  3. Richten Sie ein JWT Templatefür Convex ein. Navigieren Sie im Clerk-Dashboard zu JWT Templates, erstellen Sie ein neues Template mit dem Namen „convex“ und konfigurieren Sie die Issuer- und Audience-Felder gemäß dem Convex + Clerk-Integrationsleitfaden
  4. Kopieren Sie die JWT-Issuer-Domain in CLERK_JWT_ISSUER_DOMAIN
  5. Richten Sie einen Webhook-Endpoint ein, der auf Ihre Convex-Site-URL zeigt (z. B. https://your-deployment.convex.site/clerk-webhook). Aktivieren Sie Benutzer-Events (user.created, user.updated, user.deleted). Kopieren Sie das Signing-Secret in CLERK_WEBHOOK_SECRET
3

E2B-Sandbox-Zugriff einrichten

E2B stellt die Cloud-Sandboxes bereit, in denen KI-Agenten ausgeführt werden. Die Konfiguration erfolgt auf Projektebene innerhalb der CodeCourier-UI (Projekteinstellungen > API Keys), nicht als lokale Umgebungsvariable. Um Ihr E2B-Setup während der Entwicklung zu verifizieren:

  1. Erstellen Sie ein Konto unter e2b.dev und beziehen Sie Ihren API-Key vom Dashboard
  2. Nach dem Start von CodeCourier navigieren Sie zu den Projekteinstellungen und fügen Sie Ihren E2B-API-Key im Bereich API Keys hinzu

Das E2B-SDK (Paket e2b) ist bereits in den Projekt-Abhängigkeiten enthalten. Sandbox-Templates (die die Basis-Umgebung und vorinstallierten Tools definieren) werden pro Workflow konfiguriert und über die CodeCourier-UI verwaltet.

4

Trigger.dev verbinden

Trigger.dev übernimmt die Ausführung von Hintergrund-Jobs für Sandbox-Provisionierung, Workflow-Läufe und Issue-Sessions. Für die lokale Entwicklung:

  1. Registrieren Sie sich unter trigger.dev und erstellen Sie ein neues Projekt
  2. Installieren Sie die Trigger.dev-CLI global oder verwenden Sie npx:
Terminal
npx trigger.dev@latest dev

Dies startet den Trigger.dev-Dev-Server, der sich mit der Trigger.dev-Cloud verbindet, um Jobs lokal zu empfangen und zu verarbeiten. Das Projekt enthält eine Datei trigger.config.ts, die alle registrierten Tasks definiert.

Trigger.dev ist für UI-Entwicklung optional

Wenn Sie nur am Frontend arbeiten und keine echte Sandbox-Ausführung testen müssen, können Sie das Trigger.dev-Setup überspringen. Die UI lädt weiterhin und zeigt Daten aus Convex an - Läufe und Sandboxes werden nur nicht ausgeführt.

Entwicklungsserver starten

Während Convex Dev in einem Terminal läuft, starten Sie den Next.js-Entwicklungsserver in einem anderen:

Terminal
bun dev

Die Anwendung startet unter http://localhost:3000. Sie sollten die Clerk-Anmeldeseite sehen. Nach der Authentifizierung werden Sie geleitet, Ihr erstes Projekt zu erstellen oder einem bestehenden beizutreten.

Installation überprüfen

Gehen Sie diese Checkliste durch, um zu bestätigen, dass alles funktioniert:

  1. Authentifizierung: Sie können sich über Clerk an- und abmelden. Ihr Benutzer erscheint im Convex-Dashboard unter der Tabelle users.
  2. Projekterstellung: Sie können ein neues Projekt erstellen. Prüfen Sie, ob die Tabellen projects, projectMembers und projectSettings in Convex gefüllt werden.
  3. Echtzeit-Updates: Öffnen Sie zwei Browser-Tabs am selben Projekt. Erstellen Sie in einem Tab einen Workflow und bestätigen Sie, dass er sofort im anderen erscheint.
  4. API-Key-Speicherung: Fügen Sie in den Projekteinstellungen einen E2B-API-Key hinzu und überprüfen Sie, dass nur die letzten vier Zeichen sichtbar sind.

Tests ausführen

CodeCourier enthält sowohl Unit-Tests (Vitest) als auch End-to-End-Tests (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

Fehlerbehebung

Convex Dev startet nicht

Stellen Sie sicher, dass Sie in der Convex-CLI angemeldet sind (npx convex login) und dass Ihre Datei convex.json auf ein gültiges Projekt zeigt. Wenn Sie Schema-Validierungsfehler sehen, prüfen Sie, dass alle Dateien im Verzeichnis convex/ ohne TypeScript-Fehler kompilieren.

Endlosschleife bei Clerk-Authentifizierungs-Weiterleitungen

Überprüfen Sie, dass NEXT_PUBLIC_CLERK_PUBLISHABLE_KEYmit der Umgebung Ihrer Clerk-Anwendung übereinstimmt (Test vs. Produktion). Stellen Sie sicher, dass das JWT-Template in Clerk „convex“ heißt und die Issuer-Domain in CLERK_JWT_ISSUER_DOMAIN exakt passt.

Sandbox-Erstellung schlägt fehl

Prüfen Sie, dass Ihr E2B-API-Key in den Projekteinstellungen korrekt konfiguriert ist (nicht in .env.local - E2B-Schlüssel werden projektweise in Convex gespeichert). Überprüfen Sie, dass der Trigger.dev-Dev-Server läuft und verbunden ist. Sehen Sie sich die Job-Ausführungs-Logs im Trigger.dev-Dashboard an.

Typprüfungs-Fehler

Führen Sie den Typ-Checker aus, um Probleme zu finden:

Terminal
npm run typecheck

Das Projekt verwendet TypeScript 5.9+ mit Strict Mode. Convex generiert Typen automatisch in convex/_generated/- wenn diese fehlen, stellen Sie sicher, dass npx convex dev mindestens einmal ausgeführt wurde.

Nächste Schritte

Kernkonzepte

Verstehen Sie das Datenmodell und wie die Funktionen von CodeCourier zusammenhängen.

Ihr erstes Projekt

Detaillierte Anleitung zur Konfiguration eines Projekts für den realen Einsatz.