Initial Setup

Complete guide to get Yugen running locally.

Clone and Install

gh repo create your-project-name --private

git clone git@github.com:code-and-creed/yugen.git your-project-name
cd your-project-name

rm -rf .git

bun install

git remote remove upstream
git remote add origin git@github.com:your-username/your-project-name.git

bun run rename-project [your-project-name]

git add .
git commit -m "Initial commit"
git push origin main

cp .env.convex.dev.example .env.convex.dev

Provider Setup

Set up these provider accounts and add the credentials to your .env.convex.dev file:

1. Convex

Just sign up for a free account if you haven't already.

No credentials needed yet - we'll create the project in the next section.

2. BetterAuth

Generate Auth Secret:

openssl rand -base64 32

Add this value to your .env.convex.dev file as BETTER_AUTH_SECRET.

OAuth Providers (Optional):

Add Google, GitHub, or other OAuth providers for social authentication.

3. Polar.sh (Payments)

Get these values:

1. Create an organization
2. Copy your Organization ID (Settings → Profile → Identifier)
3. Go to Settings → API → Create Personal Access Token
4. Call it dev and set the expiration to No expiration click Select All for the scopes
5. Click Create Token

Add these to your .env.convex.dev file as:

• POLAR_ORGANIZATION_ID
• POLAR_ACCESS_TOKEN

4. Resend (Email)

Get API Key:

1. Go to Resend Dashboard → API Keys → Create
2. Copy the API key (starts with re_)

Add these to your .env.convex.dev file as:

• RESEND_API_KEY
• SENDER_EMAIL (use onboarding@resend.dev for development)
• COMPANY_NAME (your company name)

Domain Setup (Production only):

1. Go to Domains → Add Domain
2. Enter your domain (e.g., yourdomain.com)
3. Add required DNS records to your domain registrar:
   • TXT record for domain verification
   • MX record for email routing
   • CNAME record for SPF/DKIM
4. Wait for verification (12-48 hours for DNS propagation)

5. Cloudflare R2 (Storage)

Create R2 Bucket:

1. Navigate to Storage & databases → R2 object storage → Overview
2. Click Create Bucket
3. Name: your-bucket-name-dev (for development)
4. Click Create Bucket

Get API Credentials:

1. In the R2 dashboard, click Manage (next to "API Tokens" in the Account Details section)
2. Click Create Account API Token
3. Configure the token:
   • Token name: Give it a descriptive name (e.g., "Yugen Dev")
   • Permissions: Select Object Read & Write
   • Specify bucket(s): Choose Apply to specific buckets only
   • Select your bucket from the dropdown (e.g., your-bucket-name-dev)
   • TTL: Leave as Forever (or set expiration if preferred)
4. Click Create Account API Token
5. Copy these values immediately (Secret Access Key is only shown once!):
   • Access Key ID → R2_ACCESS_KEY_ID
   • Secret Access Key → R2_SECRET_ACCESS_KEY
6. Get your Account ID from the R2 dashboard (shown in the Account Details section) → R2_ACCOUNT_ID

Set CORS Policy:

1. Go to Your Bucket → Settings → CORS Policy
2. Add this policy:

[
  {
    "AllowedOrigins": ["http://localhost:3002", "https://*.ngrok.app"],
    "AllowedMethods": ["GET", "PUT", "POST", "DELETE"],
    "AllowedHeaders": ["*"],
    "ExposeHeaders": ["ETag"],
    "MaxAgeSeconds": 3600
  }
]

Add these to your .env.convex.dev file as:

• R2_ACCESS_KEY_ID
• R2_SECRET_ACCESS_KEY
• R2_ACCOUNT_ID
• R2_BUCKET_NAME

Configure Services

bun run dev:setup

VITE_CONVEX_SITE_URL=https://your-project.convex.site
SITE_URL=http://localhost:3002

# BetterAuth
BETTER_AUTH_SECRET="<your-generated-secret>"

# Polar.sh
POLAR_ORGANIZATION_ID=<your-org-id>
POLAR_ACCESS_TOKEN=polar_pat_...

# Resend
RESEND_API_KEY=re_...
SENDER_EMAIL=onboarding@resend.dev
COMPANY_NAME=YourCompanyName

# Cloudflare R2
R2_ACCESS_KEY_ID=...
R2_SECRET_ACCESS_KEY=...
R2_ACCOUNT_ID=...
R2_BUCKET_NAME=your-bucket-name-dev

# Site URL
SITE_URL=http://localhost:3002

cp apps/web/.env.example apps/web/.env.local

VITE_CONVEX_URL=https://your-project.convex.cloud
VITE_CONVEX_SITE_URL=https://your-project.convex.site
SITE_URL=http://localhost:3002

bun run setup:convex:dev

bun alchemy login

Start Development

bun alchemy dev

bun run dev

Verify Setup

After starting the development servers:

1. Visit the App
   • Open http://localhost:3002 in your browser
   • You should see the default Yugen landing page

2. Test Authentication
   • Click sign up button
   • Create an account with email/password
   • Should redirect after successful authentication

3. Check Convex Dashboard
   • Go to Convex dashboard → Data → Tables
   • Click on users table
   • Verify new user appears ✅

Testing Webhooks Locally (Optional)

To test Polar.sh webhooks (payments only) or email sending locally, you'll need ngrok:

brew install ngrok

ngrok http 3002

SITE_URL=https://abc123.ngrok.app

server: {
  allowedHosts: ["abc123.ngrok.app"],
}

bun run setup:convex:dev

# Restart both terminals
bun run dev  # From root
bun alchemy dev  # From apps/web/

Next Steps

We recommend you deploy immediately to production. Follow the Production Deployment guide to get your app live and then you can start iterating.