Signal/docs/phase3-setup-checklist.md

Phase 3 Setup Checklist

Clerk + Supabase + Railway Staging

Run these steps in order. Code is already written — you just need the keys.

---

Step 1: Clerk Account Setup

1. Go to clerk.com and create an account

2. Create a new application — name it Signal

3. Select React as the framework

4. From Dashboard > API Keys, copy:

   • Publishable Key (starts with pk_test_...) — goes in the frontend .env
   • Secret Key (starts with sk_test_...) — NOT needed for our approach (we use JWKS)

5. From Dashboard > API Keys > Show API URLs, copy the Frontend API URL

   • Looks like: https://clean-mayfly-62.clerk.accounts.dev
   • Your JWKS URL is: <Frontend API URL>/.well-known/jwks.json
   • Example: https://clean-mayfly-62.clerk.accounts.dev/.well-known/jwks.json
   • This goes in Railway as CLERK_JWKS_URL

6. From Dashboard > Configure > Organizations, enable Organizations

   • Create one organization named Gaboro DME with slug gaboro-pilot
   • Copy the Organization ID (starts with org_...) — you'll need it for the SQL step below
   • Add yourself as a member of that organization

7. From Dashboard > Configure > Domains, add:

   • http://localhost:5173 (local dev)
   • Your Vercel production URL when it's live

---

Step 2: Supabase Staging Project

1. Go to supabase.com, create a new project named signal-staging
2. Wait for it to provision (2-3 minutes)
3. Go to Settings > API, copy:
   • Project URL (looks like https://xxxxxxxxxxxx.supabase.co)
   • Service Role Key — must be the long eyJ... JWT format (NOT the sb_ format)
4. Go to SQL Editor, run the migration SQL below

---

Step 3: SQL Migration

Run on BOTH Supabase projects (production + staging)

-- Add Clerk org ID column to organizations table
ALTER TABLE organizations
  ADD COLUMN IF NOT EXISTS clerk_org_id TEXT UNIQUE;

-- Update the pilot org with the real Clerk org ID
-- Replace org_xxxxxxxxxxxxxxxx with the actual org ID from Clerk Dashboard
UPDATE organizations
  SET clerk_org_id = 'org_xxxxxxxxxxxxxxxx'
  WHERE slug = 'gaboro-pilot';

-- Helper function for RLS policies (reads Clerk org ID from JWT)
CREATE OR REPLACE FUNCTION requesting_owner_id()
RETURNS TEXT
LANGUAGE SQL
STABLE
AS $$
  SELECT COALESCE(
    (auth.jwt() -> 'o') ->> 'id',
    auth.jwt() ->> 'sub'
  );
$$;

-- RLS on organizations
ALTER TABLE organizations ENABLE ROW LEVEL SECURITY;
CREATE POLICY "org_members_see_own_org"
  ON organizations FOR SELECT
  USING (clerk_org_id = requesting_owner_id());

-- RLS on upload_batches
ALTER TABLE upload_batches ENABLE ROW LEVEL SECURITY;
CREATE POLICY "org_members_see_own_batches"
  ON upload_batches FOR SELECT
  USING (org_id IN (
    SELECT id FROM organizations WHERE clerk_org_id = requesting_owner_id()
  ));
CREATE POLICY "org_members_insert_own_batches"
  ON upload_batches FOR INSERT
  WITH CHECK (org_id IN (
    SELECT id FROM organizations WHERE clerk_org_id = requesting_owner_id()
  ));

-- RLS on normalized_records
ALTER TABLE normalized_records ENABLE ROW LEVEL SECURITY;
CREATE POLICY "org_members_see_own_records"
  ON normalized_records FOR SELECT
  USING (EXISTS (
    SELECT 1 FROM upload_batches ub
    JOIN organizations o ON o.id = ub.org_id
    WHERE ub.id = normalized_records.batch_id
      AND o.clerk_org_id = requesting_owner_id()
  ));

-- RLS on report_runs
ALTER TABLE report_runs ENABLE ROW LEVEL SECURITY;
CREATE POLICY "org_members_see_own_runs"
  ON report_runs FOR SELECT
  USING (org_id IN (
    SELECT id FROM organizations WHERE clerk_org_id = requesting_owner_id()
  ));

-- RLS on export_files
ALTER TABLE export_files ENABLE ROW LEVEL SECURITY;
CREATE POLICY "org_members_see_own_exports"
  ON export_files FOR SELECT
  USING (EXISTS (
    SELECT 1 FROM report_runs rr
    JOIN organizations o ON o.id = rr.org_id
    WHERE rr.id = export_files.report_run_id
      AND o.clerk_org_id = requesting_owner_id()
  ));

-- NOTE: source_files and mapping_decisions are write-once audit records.
-- The backend uses the service role key for writes (bypasses RLS by design).
-- Add SELECT policies here when frontend reads are needed in a later phase.

---

Step 4: Connect Supabase to Clerk (Native Integration)

In Clerk Dashboard:

1. Go to Configure > Integrations (or search "Supabase")
2. Click Activate Supabase integration
3. Copy your Clerk domain shown there

In Supabase Dashboard (repeat for BOTH projects):

1. Go to Authentication > Sign In / Sign Up > Third Party Auth
2. Click Add provider > select Clerk
3. Paste the Clerk domain
4. Save

This makes Supabase trust Clerk JWTs — no custom templates needed.

---

Step 5: Set Railway Environment Variables

Production environment:

In Railway > signal-api > production > Variables, add:

CLERK_JWKS_URL = https://eternal-goblin-1.clerk.accounts.dev/.well-known/jwks.json

Staging environment:

In Railway > signal-api > staging > Variables, add:

CLERK_JWKS_URL    = https://eternal-goblin-1.clerk.accounts.dev/.well-known/jwks.json
SUPABASE_URL      = https://<staging-project>.supabase.co
SUPABASE_ANON_KEY = eyJ... (anon key from staging project)
SUPABASE_SERVICE_KEY = eyJ... (service role key from staging project)

Staging already has SIGNAL_API_KEY and ALLOWED_ORIGINS set.

---

Step 6: Set Frontend .env

Edit signal-ui/.env:

VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxxxxxxxxxxxxxxx

---

Step 7: Deploy Staging Backend

Once all Railway staging vars are set, trigger a deploy:

cd /Users/sttil-solutions/projects/signal
railway up --detach --environment staging -m "Phase 3: Clerk auth + staging env"

---

Staging API Key (save this)

The staging environment uses a separate API key for direct testing:

r0C6vm1RLeg84lB9jeZ5sSRieDZWsLL0dAMDfEcXubE