Skip to main content

Metabase Local Testing - Quick Start

🚀 Quick Start (5 minutes)​

1. Start Metabase​

docker compose up metabase -d

Wait ~30 seconds, then open: http://localhost:3002

2. Configure Metabase​

  1. Complete initial setup (create admin account)
  2. Go to Settings → Admin → Embedding
  3. Click "Static embedding" tab (free, not the paid "Embedded Analytics")
  4. Enable static embedding and copy the secret key

3. Add to .env​

METABASE_SITE_URL=http://localhost:3002
METABASE_EMBED_SECRET_KEY=<paste-secret-key-here>

4. Restart Backend​

# If using Docker
docker compose restart backend

# If running directly
cd apps/backend && pnpm start:dev

5. Create Test Dashboard​

  1. In Metabase: Browse Data → Native Query
  2. Run: SELECT '{{business_id}}' AS business_id, CURRENT_DATE AS test_date
  3. Add variable: business_id (type: Text)
  4. Save as question → Create dashboard
  5. Enable embedding on dashboard
  6. Lock and hide business_id parameter
  7. Note the Dashboard ID from URL

6. Test Backend​

# Use the test script
./scripts/test-metabase-local.sh

# Or manually with curl
curl -X GET "http://localhost:4000/reports/dashboard/1/embed-url?businessId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <YOUR_FIREBASE_TOKEN>"

7. Test Frontend​

Add to any page:

import { MetabaseDashboardFrame } from "@/features/reports/MetabaseDashboardFrame";

<MetabaseDashboardFrame dashboardId={1} height="600px" />

✅ Checklist​

  • Metabase running on http://localhost:3002
  • Embedding enabled in Metabase
  • METABASE_SITE_URL in .env
  • METABASE_EMBED_SECRET_KEY in .env (matches Metabase)
  • Backend restarted with new env vars
  • Test dashboard created with business_id parameter
  • Backend endpoint returns embed URL
  • Frontend component loads dashboard

🐛 Common Issues​

IssueSolution
"METABASE_SITE_URL is not configured"Add to .env and restart backend
"Invalid token" in dashboardSecret keys don't match - check both places
Dashboard shows no dataAdd WHERE business_id = {{business_id}} to query
Can't access MetabaseCheck docker compose ps metabase

📚 Full Documentation​

See local-testing-guide.md for detailed instructions.