Local Development

The local development setup runs Inngest as a Docker container alongside PostgreSQL, Redis, and other services. The Inngest Dev Server provides a local dashboard for inspecting events, function runs, and step results.

Starting the Dev Server

The Inngest container is included in the root docker-compose.yml and starts automatically with:

pnpm docker:up

This runs the inngest/inngest:latest image in dev mode:

inngest:
  image: inngest/inngest:latest
  container_name: trovella-inngest
  restart: unless-stopped
  ports:
    - "8288:8288"
  command: >
    inngest dev
    --host 0.0.0.0
    --port 8288
    --no-discovery

The --no-discovery flag prevents the dev server from scanning the network for SDK registrations. The Next.js app registers explicitly when it starts.

Environment Variables

The following variables are needed in apps/web/.env for local development:

INNGEST_DEV=1              # Tells the SDK to skip signing key validation
INNGEST_BASE_URL=http://localhost:8288  # Points to the local dev server

The INNGEST_DEV=1 flag is critical. Without it, SDK v4 silently returns 500 errors on every request because no signing key is configured locally.

INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY are not needed for local development -- they are production-only and stored in GCP Secret Manager.

Local Dashboard

Once pnpm docker:up and pnpm dev are both running, open the Inngest Dev Server dashboard:

http://localhost:8288

The dashboard shows:

• Events -- every event sent by the app, with full payload inspection
• Functions -- registered functions and their configuration
• Runs -- execution history with step-by-step breakdown
• Logs -- per-step output and timing

Testing Functions Manually

Trigger from the dashboard

The Inngest Dev Server dashboard lets you send test events directly. Navigate to the Events tab, select an event type, and compose a payload:

{
  "name": "search/content.created",
  "data": {
    "sourceTable": "research_artifact",
    "sourceId": "test-123",
    "title": "Test Document",
    "content": "This is test content for the indexing pipeline.",
    "organizationId": "org-id-from-seed",
    "userId": "user-id-from-seed"
  }
}

Trigger from code

During development, you can send events programmatically using the Inngest client:

import { inngest } from "@/inngest/client";

await inngest.send({
  name: "search/content.created",
  data: {
    sourceTable: "research_artifact",
    sourceId: "test-456",
    title: "Test",
    content: "Content to index.",
    organizationId: "org-id",
    userId: "user-id",
  },
});

Without Inngest running

The event emitter in @repo/mcp no-ops when INNGEST_BASE_URL and INNGEST_DEV are both unset. This means:

• Database seeding (pnpm db:seed) works without Inngest
• Tests run without Inngest
• MCP tool calls succeed but skip background indexing

Production vs Local Differences

Aspect	Local	Production
Inngest mode	inngest dev	inngest start
Authentication	INNGEST_DEV=1 (no signing)	Signing key + event key via CLI flags
Dashboard access	http://localhost:8288	SSH tunnel to port 8288
State storage	In-memory (resets on restart)	Cloud SQL PostgreSQL
SDK URL	Auto-discovered or manual	--sdk-url http://web:3000/api/inngest
Container name	trovella-inngest	inngest (in Docker Compose service)

Troubleshooting

Functions not appearing in the dashboard

The Next.js dev server must be running (pnpm dev) for functions to register. Inngest discovers functions by calling GET /api/inngest on the app. If the app is not running, the functions list will be empty.

Events sent but functions not executing

1. Check that INNGEST_DEV=1 is set in apps/web/.env
2. Check that INNGEST_BASE_URL=http://localhost:8288 is set
3. Verify the Inngest container is running: docker ps | grep inngest
4. Check the Inngest dashboard for error details

500 errors from /api/inngest

This almost always means INNGEST_DEV=1 is missing. SDK v4 requires either dev mode or a valid signing key. The error is silent -- no useful message is returned.