Supabase Setup

CareNova uses Supabase as its backend infrastructure for authentication, database hosting, and file storage.

This guide walks you through the complete Supabase configuration required before running CareNova for the first time.

Before you begin — complete the Installation Guide steps first. You should already have your .env.local file created and ready to fill in.

Step 1 — Create a Supabase Account

If you do not already have a Supabase account, create one at:

supabase.com → Click Start your project

The free tier is sufficient for development and small production deployments.

Video: Getting started with Supabase

Step 2 — Create a New Project

After logging in to app.supabase.com:

1. Click New Project

2. Select your organization

3. Enter a project name — for example: carenova

4. Set a strong database password — save this password immediately, you will need it for your connection strings

5. Select the region closest to your users for best performance

6. Click Create new project

Supabase will provision your project in approximately 1–2 minutes. Wait for the status to show healthy before continuing.

Choose your region carefully. Once a project is created, the region cannot be changed without creating a new project.

Step 3 — Retrieve API Credentials

Navigate to Settings → API in your Supabase project.

Copy the following values into your .env.local file:

NEXT_PUBLIC_SUPABASE_URL=https://your-project-ref.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

The SUPABASE_SERVICE_ROLE_KEY bypasses Row Level Security and has full database access. Keep it server-side only and never commit it to a public repository.

Step 4 — Configure Database Connection

CareNova requires two database connection strings — one for application queries and one for migrations.

Navigate to Settings → Database → Connection String.

Transaction Pooler — Port 6543 (Required)

Select Transaction mode and copy the connection string.

Replace [YOUR-PASSWORD] with your actual database password:

DATABASE_URL=postgresql://postgres.[ref]:[YOUR-PASSWORD]@aws-0-[region].pooler.supabase.com:6543/postgres?pgbouncer=true

The ?pgbouncer=true parameter at the end is required. CareNova uses Drizzle ORM with prepare: false for pgBouncer transaction mode compatibility. Without this, queries will fail.

Session Mode — Port 5432 (Optional, for migrations)

Select Session mode and copy the connection string:

DIRECT_DATABASE_URL=postgresql://postgres.[ref]:[YOUR-PASSWORD]@aws-0-[region].pooler.supabase.com:5432/postgres

DIRECT_DATABASE_URL is only needed when running npm run db:migrate. For regular development and production use, only DATABASE_URL is required.

If your database password contains special characters, URL-encode them before adding to the connection string. For example, @ becomes %40, # becomes %23.

Helpful resources:

• Supabase connection pooling

• pgBouncer transaction mode

Step 5 — Initialize the Database

CareNova includes a master SQL installation file that creates all 35+ tables, indexes, enums, and default data in one step.

1. In your Supabase project, go to SQL Editor

2. Click New query

3. Open INSTALL.sql from your carenova-app/ folder

4. Copy the entire file contents

5. Paste into the SQL Editor

6. Click Run

The script will output a list of all created tables when complete. This confirms the installation was successful.

-- Expected output (partial):
-- appointments
-- auth_audit_log
-- blog_categories
-- blog_posts
-- clinics
-- departments
-- diagnoses
-- expenses
-- ...and 25+ more tables

INSTALL.sql is idempotent — it uses CREATE TABLE IF NOT EXISTS throughout. Running it multiple times is safe and will not duplicate or overwrite existing data.

Helpful resources:

• Supabase SQL Editor guide

Step 6 — Configure Authentication

Enable Email Provider

Navigate to Authentication → Providers and confirm that the Email provider is enabled.

Recommended settings:

Disabling email confirmation is acceptable for local development to speed up testing. Always enable it for production deployments.

Configure Redirect URLs

Navigate to Authentication → URL Configuration:

Add the following Redirect URLs (add each separately):

http://localhost:3000/auth/callback
http://localhost:3000/auth/confirm
http://localhost:3000/auth/reset-password
https://yourdomain.com/auth/callback
https://yourdomain.com/auth/confirm
https://yourdomain.com/auth/reset-password

If redirect URLs are not configured correctly, email confirmation links will fail and users will not be able to complete registration.

Update Email Templates

Navigate to Authentication → Email Templates.

Select Confirm signup and replace the default template with the following:

<html>
  <body style="font-family: sans-serif; background: #f9fafb; 
               padding: 40px 0;">
    <div style="max-width: 480px; margin: 0 auto; 
                background: white; border-radius: 12px; 
                padding: 40px; box-shadow: 0 1px 3px rgba(0,0,0,0.1);">
      <h2 style="color: #111827; margin-bottom: 8px;">
        Confirm your email
      </h2>
      <p style="color: #6b7280; margin-bottom: 24px;">
        Click the button below to confirm your email address 
        and activate your CareNova account.
      </p>
      <a href="{{ .ConfirmationURL }}" 
         style="display: inline-block; background: #4f46e5; 
                color: white; padding: 12px 24px; 
                border-radius: 8px; text-decoration: none; 
                font-weight: 600;">
        Confirm Email Address
      </a>
      <p style="color: #9ca3af; font-size: 13px; margin-top: 24px;">
        If you did not create an account, you can ignore 
        this email.
      </p>
    </div>
  </body>
</html>

The {{ .ConfirmationURL }} variable is required. Supabase replaces it with the actual confirmation link.

Step 7 — Configure SMTP (Email Sending)

CareNova uses Resend for transactional emails. Without this configuration, confirmation emails will not be delivered.

Create a Resend Account

1. Go to resend.com and create a free account

2. Go to Domains and add your domain

3. Add the required DNS records to your domain provider

4. Wait for domain verification (usually a few minutes)

5. Go to API Keys and create a new key

6. Copy the key — it starts with re_

Add it to your .env.local:

RESEND_API_KEY=re_xxxxxxxxxx

Configure SMTP in Supabase

Navigate to Authentication → SMTP Settings and enable Custom SMTP:

Click Save and then Send test email to verify the configuration is working.

Without a verified sending domain in Resend, emails will not be delivered. The domain must match the sender email address configured in Supabase SMTP.

Helpful resources:

• Resend documentation

• Supabase custom SMTP guide

Step 8 — Create Storage Buckets

CareNova requires four storage buckets for file uploads. Create them manually in your Supabase project.

Navigate to Storage in your project dashboard.

For each bucket below, click New bucket, enter the name, set it to Public, and click Create bucket:

All four buckets must be set to Public. CareNova accesses uploaded files via public URL. Private buckets will cause file display to break.

After creating each bucket, you do not need to configure any additional policies. CareNova handles file validation server-side before upload.

Video: How to create Supabase storage buckets

Step 9 — Verify Configuration

Run through this checklist to confirm Supabase is fully configured:

• [ ] Supabase project is active and showing healthy status

• [ ] NEXT_PUBLIC_SUPABASE_URL copied to .env.local

• [ ] NEXT_PUBLIC_SUPABASE_ANON_KEY copied to .env.local

• [ ] SUPABASE_SERVICE_ROLE_KEY copied to .env.local

• [ ] DATABASE_URL set with port 6543 and ?pgbouncer=true

• [ ] INSTALL.sql has been run in SQL Editor successfully

• [ ] All 35+ tables visible in Table Editor

• [ ] Email provider enabled in Authentication → Providers

• [ ] Redirect URLs configured in Authentication → URL Configuration

• [ ] Email template updated in Authentication → Email Templates

• [ ] Resend SMTP configured and test email sent successfully

• [ ] All four storage buckets created and set to Public

If all items are checked, your Supabase configuration is complete. ✅

Troubleshooting

Database connection fails:

• Confirm DATABASE_URL uses port 6543 not 5432

• Confirm ?pgbouncer=true is appended to the URL

• Check that your database password is correct

• Confirm the Supabase project is not paused (free tier projects pause after 1 week of inactivity)

Email confirmation not sending:

• Confirm Resend domain is verified

• Confirm SMTP settings match exactly — username must be resend, password must be your API key

• Check Resend dashboard for delivery logs

• Confirm the sender email domain matches your verified Resend domain

Storage uploads failing:

• Confirm all four buckets exist and are set to Public

• Confirm SUPABASE_SERVICE_ROLE_KEY is set correctly

• Check browser console for specific error messages

Tables not appearing after running INSTALL.sql:

• Confirm you ran the script in the SQL Editor of the correct Supabase project

• Check the SQL Editor output for any error messages

• Try running the script again — it is safe to run multiple times

Next Step

Supabase is now fully configured. Continue to the Environment Variables guide for a complete reference of all configuration options, or proceed to Deployment to take CareNova to production.