Development Setup

This guide walks you through getting the main OpenCauldron Next.js application running locally so you can develop and test changes before opening a pull request.

Prerequisites

• Node.js 20+ and pnpm (the project’s package manager)
• Docker for local Postgres, or a Neon connection string
• A Google Cloud project with OAuth credentials configured for http://localhost:3000
• At least one AI provider API key (for testing generation)
• Git

---

1. Fork and clone

Fork opencauldron/opencauldron on GitHub, then clone your fork:

git clone https://github.com/YOUR_USERNAME/opencauldron
cd opencauldron

Add the upstream remote so you can pull in future changes:

git remote add upstream https://github.com/opencauldron/opencauldron

---

2. Install dependencies

pnpm install

---

3. Configure environment

Copy the example env file:

cp .env.example .env.local

Open .env.local and fill in the required values.

Required variables

# Database — local Docker Postgres (see step 4) or a Neon connection string
DATABASE_URL="postgresql://cauldron:cauldron@localhost:5432/cauldron"

# Auth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET=""      # openssl rand -base64 32

# Google OAuth
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""

For Google OAuth, create credentials at console.cloud.google.com/apis/credentials. Set the authorized JavaScript origin to http://localhost:3000 and the redirect URI to http://localhost:3000/api/auth/callback/google.

AI provider keys

Add at least one AI provider key in the AI MODELS section so you can test generation. Any key will work:

GEMINI_API_KEY=""     # Google AI Studio — free tier available

See the API Keys guide for how to obtain keys for every supported provider.

Storage

For local development, use the local filesystem backend — no credentials needed:

STORAGE_PROVIDER="local"

Note

Local storage does not work for image-to-video generation because AI provider APIs need a publicly accessible URL for the reference image. If you are working on image-to-video features, configure Cloudflare R2 instead. See the Storage guide.

---

4. Start the database

If you are using local Postgres via Docker:

docker compose up db -d

This starts a Postgres 16 container using the credentials in .env.example. The container exposes Postgres on port 5432.

If you are using Neon, skip this step and set DATABASE_URL to your Neon connection string.

---

5. Apply the schema

Apply the SQL migrations to your database:

pnpm exec drizzle-kit migrate

This applies all pending migrations in order. Use drizzle-kit migrate — not db:push. The db:push command bypasses migration history and fails on a fresh database that needs the pgvector extension.

---

6. Seed badge definitions

The feats (achievement badges) system requires a seeded badges table. Without it, no badges will be awarded and the feats UI will be empty.

pnpm exec tsx src/lib/db/seed-badges.ts

You only need to run this once (and again after upgrades that add new badges).

---

7. Start the dev server

pnpm run dev

The app starts at http://localhost:3000. Sign in with Google to create your account.

---

Development commands

Command	What it does
pnpm run dev	Start Next.js dev server with hot reload
pnpm run build	Production build — run this before opening a PR
pnpm run lint	Run ESLint across the codebase
pnpm exec drizzle-kit migrate	Apply versioned migrations
pnpm exec drizzle-kit generate	Generate a migration after editing the schema
pnpm run db:studio	Open Drizzle Studio in the browser

---

Making an admin account

After signing in for the first time, your account is created with the member role. To access admin features (user management, usage dashboards), promote yourself in Drizzle Studio:

pnpm run db:studio

Open https://local.drizzle.studio, find your row in the users table, and set role to admin.

---

Keeping your fork up to date

Before starting new work, sync your fork with upstream:

git fetch upstream
git checkout main
git merge upstream/main

---

Project structure

The main app is a standard Next.js App Router project. Key directories:

src/
├── app/                  Next.js App Router pages and API routes
│   ├── api/              API endpoints (generate, poll, upload, etc.)
│   └── (app)/            Page routes behind auth
├── components/           React components
├── lib/
│   ├── db/               Drizzle schema, client, and seed scripts
│   └── ...               Shared utilities
├── providers/            AI provider implementations + registry
└── types/                Shared TypeScript interfaces and unions

The provider system — where most new integrations live — is in src/providers/. The GenerationProvider interface and all shared types are in src/types/index.ts.

---

Verifying your changes

Before pushing a branch, run:

pnpm run lint
pnpm run build

Both must pass cleanly. The build step catches type errors that the dev server may not surface.

---

Related

• Adding a Provider — The most common contribution: adding a new AI model
• Code Style and PR Guidelines — Linting, formatting, and PR conventions
• Issues and Feature Requests — How to file a bug report or feature request