Installation Guide

This guide walks you through every step required to install CareNova, configure your environment, initialize the database, and run the application locally.

Follow each step in order for a successful installation.

Before you begin — make sure you have completed the System Requirements checklist. You will need your Supabase project, Resend account, and Envato purchase code ready before starting.

Step 1 — Download the Package

After purchasing CareNova on CodeCanyon, download the package from your Envato Downloads page.

1. Log in to your Envato account

2. Go to Downloads

3. Find CareNova and click Download

4. Select Main Files to download the full package

Extract the downloaded archive to a location on your computer.

The extracted package contains the following structure:

carenova/
├── carenova-app/        ← Main application (work here)
├── documentation/       ← CareNova documentation
├── LICENSE.txt          ← License information
├── README-FIRST.txt     ← Quick start instructions
└── install-guide.txt    ← Basic installation notes

All setup steps are performed inside the carenova-app/ directory. Do not modify files outside this folder.

Step 2 — Open the Project

Open a terminal and navigate to the application directory:

cd carenova/carenova-app

Open the project in your code editor:

code .

If you do not have VS Code installed, download it from code.visualstudio.com. It is the recommended editor for working with CareNova.

Step 3 — Install Dependencies

Install all required packages using npm:

npm install

This installs the complete dependency tree including:

• Next.js 14 and React 18

• Supabase client libraries

• Drizzle ORM

• Tailwind CSS and shadcn/ui components

• React Hook Form and Zod validation

• Framer Motion

• Recharts and dnd-kit

• next-intl for internationalization

• All other required packages

Installation may take 2–5 minutes depending on your internet connection. Do not interrupt the process.

If you encounter permission errors on macOS or Linux, do not use sudo. Instead, fix npm permissions:

npm install --legacy-peer-deps

Helpful resources:

• Node.js download

• npm documentation

Step 4 — Create Supabase Project

CareNova requires a Supabase project for authentication, database, and file storage.

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

2. Click New Project

3. Choose your organization

4. Enter a project name (e.g. carenova)

5. Set a strong database password — save this password, you will need it for your connection string

6. Select the region closest to your users

7. Click Create new project and wait for it to provision (approximately 1–2 minutes)

Video: How to create a Supabase project

Once your project is ready, retrieve the following credentials:

From Settings → API:

Keep SUPABASE_SERVICE_ROLE_KEY secret. Never expose it in client code or commit it to a public repository.

From Settings → Database → Connection String:

Select Transaction mode (port 6543) and copy the connection string. Replace [YOUR-PASSWORD] with your database password.

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

This becomes your DATABASE_URL.

The ?pgbouncer=true parameter is required. CareNova uses pgBouncer transaction mode for all database queries.

For migrations only (optional), also copy the Session mode connection string (port 5432):

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

This becomes your DIRECT_DATABASE_URL.

Helpful resources:

• Supabase documentation

• Supabase connection pooling guide

Step 5 — Configure Environment Variables

Create a new file named .env.local in the root of carenova-app/:

touch .env.local

Open .env.local and add the following variables:

# ─── Supabase (Auth + Database) ─────────────────────────────
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# ─── Database (Drizzle ORM) ──────────────────────────────────
DATABASE_URL=postgresql://postgres.[ref]:[PASSWORD]@aws-0-[region].pooler.supabase.com:6543/postgres?pgbouncer=true

# Optional: Direct connection for migrations
# DIRECT_DATABASE_URL=postgresql://postgres.[ref]:[PASSWORD]@aws-0-[region].pooler.supabase.com:5432/postgres

# ─── Supabase Service Role ───────────────────────────────────
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# ─── Site URL ────────────────────────────────────────────────
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# ─── Resend (Email) ──────────────────────────────────────────
RESEND_API_KEY=re_xxxxxxxxxx

# ─── Cron Protection ─────────────────────────────────────────
CRON_SECRET=your-random-secret-string

# ─── Envato License ──────────────────────────────────────────
ENVATO_PERSONAL_TOKEN=your-envato-personal-token
ENVATO_ITEM_ID=your-codecanyon-item-id

# ─── Demo Data (optional) ────────────────────────────────────
# DEMO_PASSWORD=Demo123!

# ─── Debug Logs (development only) ──────────────────────────
# CARENOVA_DEBUG=1

Replace all placeholder values with your actual credentials. Never commit .env.local to a public repository. The .gitignore file already excludes it by default.

Generating CRON_SECRET:

You can generate a secure random string using:

openssl rand -base64 32

Or use any random string generator. This value protects your cleanup endpoint from unauthorized access.

Full environment variable reference is available in the Environment Variables section.

Step 6 — Configure Supabase Auth

Before initializing the database, configure your Supabase authentication settings.

In Supabase Dashboard → Authentication → URL Configuration:

Set the following URLs:

In Supabase Dashboard → Authentication → Email Templates:

Update the Confirm signup email template to use your CareNova branding. The confirmation link must use {{ .ConfirmationURL }}.

In Supabase Dashboard → Authentication → SMTP Settings (if using Resend):

Video: How to configure Supabase Auth

Step 7 — Initialize the Database

CareNova provides a master SQL installation file that creates all required tables, indexes, enums, and seed data in a single operation.

Option A — Using INSTALL.sql (Recommended)

1. Open your Supabase project dashboard

2. Go to SQL Editor

3. Click New query

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

5. Copy the entire contents and paste into the SQL Editor

6. Click Run

The script will create all 35+ tables and confirm installation with a table list at the end.

INSTALL.sql is idempotent — it is safe to run multiple times. Running it again will not duplicate or overwrite existing data.

Option B — Using Drizzle push

If you prefer to use Drizzle ORM to push the schema:

npm run db:push

Option A (INSTALL.sql) is recommended for first-time setup as it includes all indexes, enums, and constraints in the correct order.

Helpful resources:

• Supabase SQL Editor guide

• Drizzle ORM documentation

Step 8 — Create Storage Buckets

CareNova includes a command that automatically creates and configures all required storage buckets in your Supabase project.

Run: bash

npm run db:buckets

This will create the following buckets:

You should see:

✓ avatars bucket ready ✓ logos bucket ready ✓ medical-attachments bucket ready ✓ landing-assets bucket ready

⚠️ SUPABASE_SERVICE_ROLE_KEY must be set in your .env.local before running this command.

Video: How to create Supabase storage buckets

Step 9 — Seed Demo Data (Optional)

CareNova includes a comprehensive demo dataset with realistic data across all modules.

Run the seed command:

npm run db:seed

This will populate your database with:

It also creates four demo user accounts:

The seed script is idempotent — running it multiple times will not create duplicate records. You can customize the demo password by setting DEMO_PASSWORD in your .env.local before seeding.

Note: Demo accounts require Supabase Auth users to be created separately. See the Demo Accounts guide for full instructions.

Step 10 — Start the Development Server

Start the local development server:

npm run dev

The application will start and display:

▲ Next.js 14.2.35 (turbo)
  - Local: http://localhost:3000
  ✓ Ready in ~1s

Open your browser and visit:

http://localhost:3000

If this is a fresh installation with no license row in the database, you will be redirected to:

http://localhost:3000/setup

Enter your Envato purchase code to activate the platform. Once activated, you will be redirected to the dashboard.

For local development without an Envato purchase code, you can insert a test license row directly into your Supabase database. See the License Activation guide for instructions.

Step 11 — Verify the Installation

Confirm the installation is working correctly:

• [ ] http://localhost:3000 loads the landing page

• [ ] The clinic type switches correctly with ?clinic=dental, ?clinic=general, ?clinic=ophthalmology

• [ ] The login page loads at /login

• [ ] You can log in with a demo account

• [ ] The dashboard loads with data visible

• [ ] Patient, Appointment, and Invoice modules are accessible

• [ ] No errors appear in the terminal

If everything loads correctly, your installation is complete. ✅

Troubleshooting

Application won't start:

• Confirm Node.js 18+ is installed: node --version

• Delete .next/ and node_modules/ and reinstall:

  npm run clean && npm install

Database connection error:

• Confirm DATABASE_URL uses port 6543 with ?pgbouncer=true appended

• Confirm your Supabase project is active and not paused

• Check that the database password in the connection string is correct and URL-encoded if it contains special characters

Login not working:

• Confirm NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY are correct

• Confirm the Supabase Auth redirect URLs are configured

• Check that the user exists in Supabase Auth → Users

Email confirmation not sending:

• Confirm RESEND_API_KEY is set and valid

• Confirm your sending domain is verified in Resend

• Check Supabase Auth → SMTP Settings are configured

Setup screen appears on every load:

• A valid license row must exist in the license table

• See the License Activation guide

Seed command fails:

• Confirm SUPABASE_SERVICE_ROLE_KEY is set in .env.local

• Confirm the database tables exist (run INSTALL.sql first)

• Check the terminal for specific error messages

Useful Commands Reference

Next Step

Once your local installation is running successfully, continue to the Supabase Setup guide for detailed storage bucket configuration and auth settings, or proceed directly to Deployment if you are ready to take CareNova to production.