Installation

This guide covers everything you need to install and deploy Hiro CRM, from setting up a local development environment to deploying to production on Vercel.

System requirements

Before installing Hiro CRM, ensure your system meets these requirements:

Node.js 20.0.0 or higher
npm 10.0.0 or higher (comes with Node.js)
Git for cloning the repository
Modern browser (Chrome, Firefox, Safari, or Edge)
Supabase account (free tier available)

Hiro CRM is tested on macOS, Linux, and Windows (via WSL2). For Windows users, we recommend using Windows Subsystem for Linux (WSL2) for the best experience.

Local development setup

Step 1: Clone the repository

Clone the Hiro CRM repository and navigate to the project directory:

git clone https://github.com/your-org/hiro-crm.git
cd hiro-crm

The project structure looks like this:

hiro-crm/
├── frontend/              # Next.js application
│   ├── app/               # App Router pages & API routes
│   ├── components/        # Reusable UI components
│   ├── lib/               # Services, utilities, integrations
│   └── public/            # Static assets
├── supabase/
│   ├── migrations/        # Database schema migrations
│   └── seeds/             # Demo data seeds
├── docs/                  # Documentation
└── scripts/               # Utility scripts

Step 2: Install dependencies

Navigate to the frontend directory and install all required packages:

cd frontend
npm install

This installs all dependencies defined in package.json, including:

Next.js 16 - React framework
@supabase/supabase-js - Supabase client
@supabase/ssr - Server-side rendering support
Tailwind CSS v4 - Utility-first CSS
Framer Motion - Animation library
OpenAI SDK - AI Assistant integration
Brevo SDK - Email/SMS campaigns
Inngest - Background job processing

Step 3: Set up Supabase

Create a new project

Visit supabase.com and sign in or create an account

Create project

Click “New Project” and fill in:

Name: hiro-crm (or your preferred name)
Database Password: Choose a strong password
Region: Select closest to your location (e.g., “West EU (Ireland)” for Spain)

Wait for provisioning

Project creation takes 1-2 minutes. Wait for the “Project is ready” notification

Get API credentials

Navigate to Settings > API and copy:

Project URL
anon public key
service_role secret key (click “Reveal” to see it)

Apply database migrations

Hiro CRM uses PostgreSQL migrations to create the database schema. You’ll need to run these in order.

Supabase CLI (Recommended)
Supabase Dashboard

Install the Supabase CLI if you haven’t already:

npm install -g supabase

Link your project and push migrations:

# From the project root directory
supabase link --project-ref your-project-ref
supabase db push

Find your project ref in the Supabase dashboard URL: https://supabase.com/dashboard/project/YOUR-PROJECT-REF

Open SQL Editor

In your Supabase dashboard, navigate to SQL Editor

Run migrations sequentially

Execute each migration file from supabase/migrations/ in numerical order:

000_MARKETING_HUB_GGP_COMPLETE_SCHEMA.sql - Core schema
001_MARKETING_HUB_GGP_HELPER_FUNCTIONS.sql - Helper functions
002_MARKETING_HUB_GGP_ENHANCEMENTS.sql - Enhancements
Continue through all numbered migrations…

Copy each file’s content, paste into the SQL editor, and click “Run”

Verify tables created

Go to Table Editor and confirm tables exist:

profiles
brands
locations
customers
reservations
campaigns
loyalty_members
And more…

Migrations must be run in numerical order. Running them out of order may cause errors due to missing dependencies.

Step 4: Configure environment variables

Create your local environment file:

cp .env.example .env.local

Edit .env.local and configure the required variables:

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

# =============================================================================
# REQUIRED: App URL
# =============================================================================
NEXT_PUBLIC_APP_URL=http://localhost:3000

Step 5: Seed demo data (optional)

To test Hiro CRM with realistic data, you can seed the database:

# Start the dev server
npm run dev

# In another terminal, seed basic data
curl http://localhost:3000/api/admin/seed-locations

Step 6: Start development server

Start the Next.js development server:

npm run dev

The application will be available at http://localhost:3000.

Use npm run dev:webpack if you experience issues with Turbopack (Next.js 16’s default bundler).

Production deployment

Deploy to Vercel

Hiro CRM is optimized for deployment on Vercel:

Push to GitHub

Push your Hiro CRM fork to GitHub:

git remote set-url origin https://github.com/your-username/hiro-crm.git
git push -u origin main

Import to Vercel

Go to vercel.com and sign in
Click “Add New” > “Project”
Import your GitHub repository
Select the frontend directory as the root

Configure environment variables

Add all required environment variables from your .env.local file:

NEXT_PUBLIC_SUPABASE_URL
NEXT_PUBLIC_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY
NEXT_PUBLIC_APP_URL (set to your Vercel domain)
Add optional variables for features you want to enable

Deploy

Click “Deploy” and wait for the build to complete (typically 2-3 minutes)

Update Supabase settings

In your Supabase project dashboard:

Go to Authentication > URL Configuration
Add your Vercel domain to Site URL and Redirect URLs

The vercel.json file in the root directory configures cron jobs for automated tasks:

Daily reservation sync (8:00 AM)
Calendar notifications (9:00 AM)
Ticket reminders (8:00 AM)
Marketing automations (every 30 minutes)

Custom domain

To use a custom domain:

Add domain in Vercel

In your Vercel project settings, go to Domains and add your custom domain

Configure DNS

Add the DNS records provided by Vercel to your domain registrar

Update environment variables

Change NEXT_PUBLIC_APP_URL to your custom domain and redeploy

Update Supabase

Add your custom domain to Supabase Authentication > URL Configuration

Additional configuration

Set up first admin user

After deployment, create your first user through the sign-up flow. Then, grant super admin permissions:

-- Run in Supabase SQL Editor
UPDATE profiles 
SET role = 'super_admin', 
    permissions = '{"super_admin": true}'::jsonb
WHERE email = '[email protected]';

Configure Supabase storage

For customer avatars and document uploads, ensure storage is configured:

Create avatars bucket

Migration 120_CREATE_AVATARS_BUCKET.sql creates this automatically

Verify storage policies

Check that Row Level Security policies allow authenticated users to upload

Enable integrations

Brevo (Email/SMS)
CoverManager POS
OpenAI (AI Assistant)

Create Brevo account

Generate API key

Go to Settings > API Keys and create a new key

Add to environment

Set BREVO_API_KEY and related variables in Vercel environment settings

Verify sender email

Verify your sender email in Brevo to enable sending

Get API credentials

Contact CoverManager support to obtain your API key

Configure in settings

Add COVERMANAGER_API_KEY to your environment variables

Sync reservations

Use the sync endpoint at /api/cron/sync or run manually from the admin panel

Create OpenAI account

Generate API key

Go to API keys and create a new secret key

Add to environment

Set OPENAI_API_KEY in your environment variables

Monitor usage

The AI Assistant uses GPT-4 by default. Monitor your usage in the OpenAI dashboard

Development tools

Available scripts

Hiro CRM includes several npm scripts for development:

# Development
npm run dev                  # Start dev server with Turbopack
npm run dev:webpack          # Start dev server with Webpack
npm run build                # Build for production
npm run start                # Start production server

# Quality checks
npm run lint                 # Run ESLint
npm run type-check           # Check TypeScript types
npm run clean                # Clean build artifacts

# Testing
npm run test                 # Run unit tests (watch mode)
npm run test:run             # Run unit tests once
npm run test:coverage        # Generate coverage report
npm run test:e2e             # Run E2E tests with Playwright
npm run test:e2e:ui          # Run E2E tests in UI mode

# Utilities
npm run verify:schema        # Verify database schema
npm run create:user          # Create test user

Database tools

For database management:

# Using Supabase CLI
supabase db diff             # Show local schema changes
supabase db push             # Push migrations to remote
supabase db pull             # Pull remote schema changes
supabase db reset            # Reset local database

Troubleshooting

Build errors

If you encounter build errors:

# Clear cache and rebuild
npm run clean
rm -rf node_modules package-lock.json
npm install
npm run build

Database connection issues

Verify credentials

Double-check your Supabase URL and keys in .env.local

Check Supabase status

Visit status.supabase.com to check for outages

Test connection

Use the Supabase dashboard to run a simple query: SELECT 1;

Type errors

Run the type checker to identify TypeScript issues:

npm run type-check

Common fixes:

Update @types/node and @types/react packages
Ensure all environment variables are properly typed in lib/env.ts

Performance issues

For production performance optimization:

Enable Vercel Analytics to monitor Core Web Vitals
Review database query performance in Supabase dashboard
Check for missing indexes on frequently queried columns

Next steps

Now that Hiro CRM is installed and running:

Configure your brand

Set up your restaurant/hotel brands and locations in the Settings panel

Import customers

Import existing customer data via CSV upload

Create campaigns

Set up your first email or SMS marketing campaign

Set up loyalty program

Configure loyalty tiers and point rewards

Getting help

If you need assistance:

Check the GitHub Issues for known problems
Review the Contributing Guide
Open a new issue with detailed information about your problem

Get Started

Core Features

Integrations

Deployment

Guides

System requirements

Local development setup

Step 1: Clone the repository

Step 2: Install dependencies

Step 3: Set up Supabase

Create a new project

Apply database migrations

Step 4: Configure environment variables

Step 5: Seed demo data (optional)

Step 6: Start development server

Production deployment

Deploy to Vercel

Custom domain

Additional configuration

Set up first admin user

Configure Supabase storage

Enable integrations

Development tools

Available scripts

Database tools

Troubleshooting

Build errors

Database connection issues

Type errors

Performance issues

Next steps

Configure your brand

Import customers

Create campaigns

Set up loyalty program

Getting help

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Deployment

Guides

​System requirements

​Local development setup

​Step 1: Clone the repository

​Step 2: Install dependencies

​Step 3: Set up Supabase

​Create a new project

​Apply database migrations

​Step 4: Configure environment variables

​Step 5: Seed demo data (optional)

​Step 6: Start development server

​Production deployment

​Deploy to Vercel

​Custom domain

​Additional configuration

​Set up first admin user

​Configure Supabase storage

​Enable integrations

​Development tools

​Available scripts

​Database tools

​Troubleshooting

​Build errors

​Database connection issues

​Type errors

​Performance issues

​Next steps

Configure your brand

Import customers

Create campaigns

Set up loyalty program

​Getting help

Build docs developers (and LLMs) love

System requirements

Local development setup

Step 1: Clone the repository

Step 2: Install dependencies

Step 3: Set up Supabase

Create a new project

Apply database migrations

Step 4: Configure environment variables

Step 5: Seed demo data (optional)

Step 6: Start development server

Production deployment

Deploy to Vercel

Custom domain

Additional configuration

Set up first admin user

Configure Supabase storage

Enable integrations

Development tools

Available scripts

Database tools

Troubleshooting

Build errors

Database connection issues

Type errors

Performance issues

Next steps

Getting help