Skip to content

Environment Setup

Jump to bottom
Luara edited this page Jul 7, 2026 · 4 revisions

Environment Setup

Complete guide to running Felines locally from scratch.

Prerequisites

  • Node.js 18 or higher
  • npm
  • A Supabase account (free tier works)
  • An OpenWeatherMap account (free tier works)

Step 1 — Clone the repository

git clone https://github.com/luarawork/felines
cd felines
npm install

Step 2 — Create a Supabase project

  1. Go to https://supabase.com and create a free account
  2. Create a new project
  3. Wait for the project to initialize (~2 minutes)
  4. Go to Project Settings → API
  5. Copy:
    • Project URL (looks like https://xxxx.supabase.co)
    • anon/public key (starts with eyJ...)

Step 3 — Get an OpenWeatherMap key

  1. Go to https://openweathermap.org and create a free account
  2. Go to My API Keys
  3. Copy your default API key

Step 4 — Create .env.local

Create a file called .env.local in the project root:

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co/ NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key NEXT_PUBLIC_WEATHER_API_KEY=your-openweathermap-key NEXT_PUBLIC_SITE_URL=http://localhost:3000

Do not commit this file. It's already in .gitignore.

Step 5 — Run database migrations

Felines has 86 SQL migrations that must be applied in order.

  1. Go to your Supabase project
  2. Open the SQL Editor
  3. For each file in supabase/migrations/ (in order from 0001 to 0086), paste the content and click Run

A few files near the end are one-time maintenance scripts (test-data cleanup, a full data wipe preserving accounts) rather than schema changes — each says so in its own header comment, and is safe to skip on a fresh database.

Or run them all at once using the Supabase CLI:

npm install -g supabase
supabase login
supabase link --project-ref your-project-ref
supabase db push

Step 6 — Run the development server

npm run dev

Open http://localhost:3000

Step 7 — Verify everything is working

  • Home page loads with no console errors
  • Map loads centered on Natal, RN
  • Weather banner shows (may take a few seconds)
  • /learn shows the article list
  • /contacts shows the 14 real contacts
  • Sign up creates a new account
  • Colony registration works after signing up

Build for production

npm run build
npm run start

The build must complete with zero errors and zero lint warnings before any commit.

Environment Variables Reference

Variable Required Where to get it
NEXT_PUBLIC_SUPABASE_URL Yes Supabase → Project Settings → API
NEXT_PUBLIC_SUPABASE_ANON_KEY Yes Supabase → Project Settings → API
NEXT_PUBLIC_WEATHER_API_KEY Yes openweathermap.org → My API Keys
NEXT_PUBLIC_SITE_URL No — defaults to http://localhost:3000 Used to build absolute links

All variables have the NEXT_PUBLIC_ prefix, which means they are intentionally exposed to the browser. They are public keys designed to be used client-side, with security enforced by Supabase RLS.

Never use the Supabase service role key as a NEXT_PUBLIC_ variable — that key bypasses RLS and must stay server-side only.

Common Issues

Map not loading Check that the Supabase URL and anon key are correct in .env.local. Restart the dev server after changing environment variables.

Weather not showing OpenWeatherMap free keys can take up to 2 hours to activate after creation. The app handles this gracefully and hides the weather banner if the API returns an error.

Migration errors Run migrations in strict numerical order. If a migration fails, check if a previous migration was skipped. Some migrations depend on objects created by earlier ones.

Build fails with TypeScript errors Run npm run lint to see all errors. The project uses strict TypeScript — all types must be correct before build.

Clone this wiki locally