Installation Guide (Self-Host Preview)

The hosted cloud is the fastest way to use Weldr, but some teams need to run the stack locally—for offline development, security reviews, or custom integrations. Follow this guide if you have repository access and want to self-host the current preview build.

> Heads-up: We are working toward open-sourcing most of the stack. Until that split is finalized, treat this guide as an internal process for collaborators with direct repo access.

Prerequisites

• Node.js 18+

• pnpm 8+

• PostgreSQL 15+ (local install or managed service such as Supabase/Neon)

• OpenRouter API key (openrouter.ai)

• macOS, Linux, or WSL2 on Windows

1. Clone the Repository

git clone https://github.com/vonwao/mosaic-builder.git
cd mosaic-builder

2. Install Dependencies

pnpm install

3. Configure Environment Variables

Copy the template and set the required values:

cp .env.example .env.local

Minimum required keys:

OPENROUTER_API_KEY=sk-or-v1-your-key
POSTGRES_URL=postgresql://user:password@localhost:5432/weldr
AUTH_SECRET=generate-32-byte-secret
NEXTAUTH_URL=http://localhost:3000

Optional values (Redis, analytics, feature flags) are documented inline in .env.example.

4. Prepare PostgreSQL

Local Postgres (macOS/Linux)

createdb weldr
psql -d weldr -c "CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\";"

Supabase

Create a new project in Supabase.

Copy the connection string from Project Settings → Database → Connection string → Node.js.

Append ?pgbouncer=true&connection_limit=1 for serverless environments and set it as POSTGRES_URL.

Neon or Other Managed Providers

Ensure SSL is enabled (?sslmode=require) and update POSTGRES_URL accordingly.

5. Run Database Migrations

pnpm db:migrate

If you need to inspect the schema, run pnpm db:studio (Drizzle Studio) or connect via your preferred SQL tool.

6. Start the App

pnpm dev

Open http://localhost:3000 to access the chat + preview experience. Log in with the same email you use in the hosted environment; magic links work locally as long as your NEXTAUTH_URL matches the running instance.

7. Useful Commands

pnpm lint            # Lint + Biome format
pnpm test            # Playwright test suite (requires browser deps)
node scripts/check-imports.js
weldr sync <chat-id> --out ./generated  # Generate from a hosted chat locally

Troubleshooting

• Cannot reach OpenRouter – Verify your API key and network allow outbound HTTPS to openrouter.ai.

• Database SSL issues – Append ?sslmode=prefer (local) or ?sslmode=require (managed) to POSTGRES_URL.

• Auth callback mismatch – Ensure NEXTAUTH_URL matches the domain/port you are using.

• Migrations fail – Drop the database (dropdb weldr) and rerun pnpm db:migrate.

Need more help? Check docs/troubleshooting/common-issues.md or post in Slack (#weldr-docs).