Run your own Karto

Create these accounts (all free tiers are fine)

• GitHub — download the Karto code and (later) connect Vercel to your repo.
• Supabase — database, sign-in, and photo storage. Open the dashboard after signup.
• Vercel — hosts the website (optional if you only test on your laptop).

Install Node.js

• Download the LTS version from nodejs.org.
• After install, open Terminal (Mac) or PowerShell (Windows) and run node -v. You should see a version like v22.x.

Clone the repository

• Open Terminal. Pick a folder (e.g. your Desktop), then run:

git clone https://github.com/kevicebryan/Karto.git
cd Karto

Install dependencies

• Still in the Karto folder:

npm install

Create a project

• Go to supabase.com/dashboard → New project.
• Pick a name, database password (save it somewhere safe), and a region close to you.
• Wait until the project status is Active.

Run the database migrations

• In your project: SQL → New query (replace _ with your project ref in the URL, or use the sidebar).
• On your computer, open supabase/migrations/ in the Karto folder.
• Run each file below in order. Paste the full file → Run → wait for success → next file.
• 1. 20260101000000_initial_schema.sql — Tables, triggers, row-level security
• 2. 20260101000100_item_images_storage.sql — Photo bucket, storage rules, thumbnail paths
• 3. 20260101000200_items_condition_sort_key.sql — Sort column for the collection grid
• 4. 20260101000300_item_images_thumb_storage_rls.sql — Upgrade-only if step 2 was an older version (safe to run)
• In Table Editor, confirm tables profiles, binders, and items exist.

Turn on email sign-in

• Authentication → Providers → enable Email (usually on by default).
• Optional: add Google or GitHub sign-in from the same Providers page.

Copy your API keys

• Open Connect at the top of the project, or Project Settings → API.
• Copy the Project URL and the publishable key (sb_publishable_…).
• Paste them into .env.local in the next chapter.

Never put the service_role / secret key in the browser or in any NEXT_PUBLIC_ variable.

Create `.env.local`

• In the Karto folder, copy .env.example to .env.local.
• Fill in at least:

NEXT_PUBLIC_SUPABASE_URL=https://YOUR_PROJECT.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=sb_publishable_...

NEXT_PUBLIC_SUPABASE_ITEM_IMAGES_BUCKET=item-images

Auth redirect for local testing

• Supabase → Authentication → URL configuration.
• Site URL: http://localhost:3000
• Redirect URLs: add http://localhost:3000/auth/callback

Run the site on your laptop

• In the Karto folder:

npm run dev

Create your account

• Open http://localhost:3000.
• Register → complete onboarding (pick your storefront username).
• Add a test card with front/back photos — uploads create front.webp and front-thumb.webp in Storage.

Push your code to GitHub

• If you only cloned this repo, fork it on GitHub first, then point your copy at your fork:

git remote set-url origin https://github.com/YOUR_USERNAME/Karto.git
git push -u origin main

Skip this if you already own the repository on GitHub.

Import into Vercel

• Go to vercel.com/new → import your GitHub repository.
• Framework: Next.js (auto-detected).
• Before deploy, add Environment Variables (same as .env.local):
• NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY, NEXT_PUBLIC_SUPABASE_ITEM_IMAGES_BUCKET=item-images
• Click Deploy and wait for the build.

Point Supabase at your live URL

• Copy your Vercel URL (e.g. https://karto-abc.vercel.app).
• Supabase → Authentication → URL configuration.
• Set Site URL to your production URL (or keep localhost and add production under Redirect URLs only).
• Redirect URLs must include: https://YOUR_VERCEL_URL/auth/callback
• Save, then try Register or Log in on the live site.

Currency conversion

• Sign up at exchangerate-api.com and add to Vercel + .env.local:

EXCHANGE_RATE_API_KEY=your-key-here

Server-only. Do not prefix with NEXT_PUBLIC_.

Better public image URLs (advanced)

• Add SUPABASE_SERVICE_ROLE_KEY in Vercel only (never in the browser).
• Helps signed URLs for storefront photos when Storage rules are strict.

Custom domain

• Vercel → your project → Settings → Domains.
• After adding a domain, update Supabase redirect URLs to match.