Skip to content

deployment.md

Latest commit

 

History

History
155 lines (103 loc) · 4.03 KB

deployment.md

File metadata and controls

155 lines (103 loc) · 4.03 KB
Raw

Deployment Guide

Supported Deployment Shapes

This starter supports two realistic deployment modes:

  • Vercel + Neon + Cloudflare R2
  • Self-hosted Next.js server + Postgres + Cloudflare R2

The runtime assumptions are the same in both cases:

  • Postgres is reachable from the app
  • R2 is reachable for media operations
  • Auth base URLs match the public origin exactly
  • Optional providers are enabled only when their corresponding features are needed

Pre-Deployment Checklist

Before the first deploy:

  1. Copy .env.example to your deployment secret manager or hosting platform.
  2. Fill in all required database, auth, and R2 values.
  3. Decide whether email, AI assistant, try-on, or video generation are part of your first release.
  4. Create a production database branch or database.
  5. Create a production R2 bucket.
  6. Confirm your public app URL for BETTER_AUTH_URL and NEXT_PUBLIC_BETTER_AUTH_URL.

Vercel Deployment

1. Create infrastructure

  • Provision production Postgres credentials
  • Provision Cloudflare R2 credentials and bucket
  • Decide your production domain before setting auth URLs

2. Configure environment variables

Set the vars from .env.example in Vercel.

Required in all cases:

  • DATABASE_URL
  • DEV_DATABASE_URL
  • PROD_DATABASE_URL
  • BETTER_AUTH_SECRET
  • BETTER_AUTH_URL
  • NEXT_PUBLIC_BETTER_AUTH_URL
  • R2_ACCOUNT_ID
  • R2_ACCESS_KEY_ID
  • R2_SECRET_ACCESS_KEY
  • R2_BUCKET_NAME

Add optional provider vars only when you are ready to use those features.

3. Deploy the app

Run the normal Vercel deployment flow for the repository. The app already accounts for VERCEL_URL and VERCEL_BRANCH_URL in auth trusted origins when those values exist.

4. Push the database schema

From a trusted environment with production secrets:

bun run db:prod:push

5. Bootstrap marketplace data

Recommended first-run sequence:

  1. Create the marketplace-managed seller account if admin-managed catalog operations are required.
  2. Log in as an admin.
  3. Configure store settings.
  4. Add categories, brands, sizes, and colors.
  5. Upload a logo and product images.

6. Validate baseline flows

Verify:

  • storefront landing page
  • locale switching
  • admin auth
  • seller auth
  • product image upload
  • add to cart and checkout

Only then enable optional providers one by one.

Self-Hosted Deployment

1. Install dependencies

bun install

2. Provide environment variables

Export the same env surface used for Vercel deployments.

3. Build the application

bun run build

4. Push the schema

bun run db:prod:push

5. Start the server

bun run start

Run it behind your preferred reverse proxy, container platform, or process manager.

Optional Provider Enablement

Enable these only after the store works without them:

  • Resend: password reset and operational mail
  • DeepInfra: AI shopping assistant
  • OpenAI: routes or tools that still expect an OpenAI key in certain workflows
  • RunPod: virtual try-on and image-edit generation
  • Runware: generated product videos

Expected behavior when omitted:

  • The dependent feature should fail clearly or remain hidden/disabled
  • Core storefront, seller, and admin operations should stay deployable

Failure Modes To Check

Common deployment mistakes:

  • BETTER_AUTH_URL does not match the public origin
  • R2 credentials are present but point to the wrong bucket
  • Production database schema was never pushed
  • Optional AI feature is enabled in UI expectations without provider credentials
  • Marketplace-managed seller scripts are used without MARKETPLACE_INTERNAL_SUPPLIER_ID

Compatibility Notes

Current public deployment guidance remains neutral even though a few legacy internals still exist:

  • Some scripts still accept KIDSWAY_INTERNAL_SUPPLIER_ID as a legacy alias
  • Some order states still store shipped_to_kidsway
  • The optional reference-photo try-on flow still uses the kid_photos table name internally

Prefer the neutral public names in new operational docs and secrets management.