Installation

Installation Overview

This guide covers the complete installation process for MLM, including development environment setup, database configuration, and production build preparation.

Time estimate: 30-45 minutes for a complete setup including database initialization.

Prerequisites

Before you begin, ensure you have the following:

Node.js & npm

Node.js v18.0.0 or later with npm

Supabase Account

Free or paid Supabase project

Git

For cloning the repository

Code Editor

VS Code or your preferred editor

Step 1: Clone and Install Dependencies

Clone the Repository

git clone https://github.com/EdgarJr30/cilm_easy_mant.git
cd cilm_easy_mant

Install Dependencies

Install all required npm packages:

npm install

This installs the following key dependencies:

React 19.1.0 and React DOM for the UI framework
TypeScript 5.8.3 for type safety
Vite 6.3.5 as the build tool
@supabase/supabase-js 2.50.0 for database and auth
Tailwind CSS 4.1.10 for styling
React Router DOM 7.6.1 for routing
UI component libraries: Radix UI, Headless UI, Heroicons, Lucide React

Verify Installation

Check that everything installed correctly:

npm run lint

This should complete without errors.

Step 2: Environment Configuration

Create your environment configuration files:

Development Environment

Create a .env file in the project root:

# Supabase Configuration (Required)
VITE_SUPABASE_URL=https://your-project-ref.supabase.co
VITE_SUPABASE_ANON_KEY=your-supabase-anon-key

# Push Notifications (Optional)
VITE_WEB_PUSH_PUBLIC_KEY=your-vapid-public-key

# Application Environment (Optional)
VITE_APP_ENV=development

# Remote Report Layout (Optional)
VITE_ENABLE_REMOTE_REPORT_LAYOUT=false

Never commit .env files to version control. They contain sensitive credentials.

Getting Supabase Credentials

Create Supabase Project

Go to supabase.com
Create a new project or use an existing one
Wait for the project to provision (usually 2-3 minutes)

Get API Credentials

Navigate to Settings → API in your Supabase dashboard
Copy the Project URL (use as VITE_SUPABASE_URL)
Copy the anon/public key (use as VITE_SUPABASE_ANON_KEY)

Get Service Role Key (For Database Setup)

You’ll also need the service_role key for running database setup scripts:

In Settings → API, copy the service_role key
Store this securely - it bypasses Row Level Security
Use it only for server-side operations and scripts

The service_role key has full database access. Never expose it in frontend code or commit it to version control.

Configuring the Supabase Client

MLM uses a centralized Supabase client configuration at src/lib/supabaseClient.ts:

src/lib/supabaseClient.ts

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;

if (!supabaseUrl || !supabaseAnonKey) {
  throw new Error('Missing Supabase URL or anon key');
}

export const supabase = createClient(supabaseUrl, supabaseAnonKey, {
  auth: {
    persistSession: true,
    autoRefreshToken: true,
    detectSessionInUrl: true,
  },
});

This configuration ensures:

Sessions persist across browser refreshes
Auth tokens refresh automatically
OAuth redirect URLs are detected properly

Step 3: Database Setup

MLM requires a comprehensive database schema with tables, functions, triggers, RLS policies, and more.

Execute SQL Modules in Order

The database is set up using modular SQL scripts located in sql/modules/core_cmms/. Execute these in the following order:

Core Infrastructure (00-05)

Run these scripts first to set up extensions, types, tables, and relationships:

00_extensions.sql - PostgreSQL extensions (uuid-ossp, pg_net, etc.)
01_enums.sql - Custom enum types (priority, status, sections, etc.)
02_permission_action.sql - Permission action types
03_tables.sql - Core tables (users, roles, tickets, locations, etc.)
04_functions_triggers.sql - Database functions and triggers
05_fk.sql - Foreign key constraints

Views and Indexes (06-07)

06_views.sql - Database views for simplified queries
07_indexes.sql - Performance indexes

Security (08-10)

08_rls.sql - Enable Row Level Security
09_policies.sql - RLS policies for data access control
10_seed_admin_permissions.sql - Initial admin permissions

Bootstrap and Features (11-14)

11_seed_bootstrap.sql - Initial data and default roles
12_updates.sql - Schema updates and migrations
13_realtime.sql - Real-time subscriptions configuration
14_storage.sql - Storage buckets and policies

Advanced Features (15-16)

15_grants_auth.sql - Authentication grants
16_notifications.sql - Complete notification system with push support

How to Execute SQL Scripts

You can run these scripts via the Supabase dashboard or Supabase CLI:

Go to your Supabase project
Navigate to SQL Editor
Click "New Query"
Copy and paste each script content
Click "Run" to execute
Repeat for each script in order

The SQL modules are designed to be idempotent where possible. However, for a fresh setup, run them on an empty database to avoid conflicts.

Database Tables Overview

After running all scripts, you’ll have the following core tables:

Table	Purpose
`users`	User profiles linked to auth.users
`roles`	Role definitions for RBAC
`permissions`	Permission catalog
`role_permissions`	Role-to-permission mappings
`user_roles`	User-to-role assignments
`tickets`	Work orders and requests
`assignees`	Technician profiles
`locations`	Facility/location definitions
`societies`	Organization/tenant information
`special_incidents`	Predefined incident types
`announcements`	System announcements
`notification_deliveries`	In-app notifications
`notification_outbox`	Push notification queue
`ticket_comments`	Comments on tickets

Step 4: Create Your First Admin User

After database setup, create an initial admin user using the provided script:

SUPABASE_URL=https://your-project-ref.supabase.co \
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
node scripts/create-first-admin.mjs

Follow the prompts to create a user with full admin permissions.

This script uses the service role key to bypass RLS and create the initial admin. Store the credentials securely.

Step 5: Development Server

Start the development server:

npm run dev

The development server will start at http://localhost:5173 (or the next available port).

Available Scripts

Script	Purpose
`npm run dev`	Start Vite dev server with hot reload
`npm run build`	TypeScript compilation + production build
`npm run build:qa`	Build for QA environment
`npm run build:prod`	Build for production environment
`npm run lint`	Run ESLint on the codebase
`npm run preview`	Preview production build locally
`npm run admin:create-first`	Create first admin user

Step 6: Optional Features

Enable Push Notifications

To enable push notifications, you need to set up VAPID keys and Edge Functions:

Generate VAPID Keys

npx web-push generate-vapid-keys --json

This outputs a public and private key pair.

Add to Environment

Add the public key to your .env:

VITE_WEB_PUSH_PUBLIC_KEY=your-vapid-public-key

Add both keys to Supabase Edge Function secrets:

VAPID_PUBLIC_KEY
VAPID_PRIVATE_KEY
VAPID_SUBJECT (e.g., mailto:your-email@domain.com)

Deploy Edge Function

npx supabase functions deploy send-push-from-outbox \
  --project-ref your-project-ref

Configure Cron Job

Set up a cron job to process the notification outbox every minute. See the Push Notifications Setup guide for details.

Configure Real-time Subscriptions

Ensure these tables are enabled for real-time in Supabase:

Go to Database → Replication in Supabase dashboard
Enable replication for:
- notification_deliveries
- ticket_comments
- tickets
Set REPLICA IDENTITY to FULL for these tables (handled by 13_realtime.sql)

Step 7: Verify Installation

Run these checks to ensure everything is set up correctly:

Test Authentication

Navigate to /login
Sign in with your admin user
Verify you’re redirected to /inicio

Check Permissions

Visit /admin/permisos to verify RBAC is working and permissions are loaded.

Create Test Ticket

Go to /crear-ticket
Fill out the form and submit
Check /solicitudes to see the request
Accept it and verify it appears in /ordenes_trabajo

Test Notifications

If you set up push notifications, run the smoke test:

SUPABASE_URL=https://your-project-ref.supabase.co \
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key \
TEST_RECIPIENT_USER_ID=your-user-uuid \
node scripts/notifications-smoke.mjs

Troubleshooting

Missing Supabase URL or anon key error

Cause: Environment variables not loaded.Solution:

Ensure .env file is in project root
Restart the dev server after creating .env
Verify variable names start with VITE_

Permission denied errors

Cause: RLS policies blocking access or missing permissions.Solution:

Verify all SQL scripts executed successfully
Check user has correct role assignments in user_roles table
Verify role has necessary permissions in role_permissions table
Check browser console for specific RLS errors

SQL script execution fails

Cause: Scripts run out of order or conflicting schema.Solution:

Drop and recreate database for clean slate
Execute scripts in exact numeric order (00-16)
Check Supabase SQL editor logs for specific errors

Real-time notifications not working

Cause: Realtime not configured or replica identity not set.Solution:

Enable replication for required tables in Supabase dashboard
Verify 13_realtime.sql executed successfully
Check browser console for WebSocket connection errors

Build fails with TypeScript errors

Cause: Type errors in code or missing dependencies.Solution:

# Clean and reinstall
rm -rf node_modules package-lock.json
npm install

# Run type check
npm run build

Production Deployment

For production deployment, see the Deployment Guide which covers:

Environment-specific configuration
Production build optimization
Supabase production setup
Edge Function deployment
PWA and push notification setup

Next Steps

Configure Your Instance

Set up locations, societies, and system settings

User Management

Add users and configure roles

Inventory Setup

Configure warehouses, parts, and stock management

Technical Architecture

Understand the system architecture

For questions or issues not covered here, check the GitHub repository or open an issue.

Getting Started

Core Features

Inventory Management

Asset Management

Reporting & Analytics

Administration

Installation Overview

Prerequisites

Node.js & npm

Supabase Account

Git

Code Editor

Step 1: Clone and Install Dependencies

Step 2: Environment Configuration

Development Environment

Getting Supabase Credentials

Configuring the Supabase Client

Step 3: Database Setup

Execute SQL Modules in Order

How to Execute SQL Scripts

Database Tables Overview

Step 4: Create Your First Admin User

Step 5: Development Server

Available Scripts

Step 6: Optional Features

Enable Push Notifications

Configure Real-time Subscriptions

Step 7: Verify Installation

Troubleshooting

Production Deployment

Next Steps

Configure Your Instance

User Management

Inventory Setup

Technical Architecture

Build docs developers (and LLMs) love

Getting Started

Core Features

Inventory Management

Asset Management

Reporting & Analytics

Administration

Documentation Index

​Installation Overview

​Prerequisites

Node.js & npm

Supabase Account

Git

Code Editor

​Step 1: Clone and Install Dependencies

​Step 2: Environment Configuration

​Development Environment

​Getting Supabase Credentials

​Configuring the Supabase Client

​Step 3: Database Setup

​Execute SQL Modules in Order

​How to Execute SQL Scripts

​Database Tables Overview

​Step 4: Create Your First Admin User

​Step 5: Development Server

​Available Scripts

​Step 6: Optional Features

​Enable Push Notifications

​Configure Real-time Subscriptions

​Step 7: Verify Installation

​Troubleshooting

​Production Deployment

​Next Steps

Configure Your Instance

User Management

Inventory Setup

Technical Architecture

Build docs developers (and LLMs) love

Installation Overview

Prerequisites

Step 1: Clone and Install Dependencies

Step 2: Environment Configuration

Development Environment

Getting Supabase Credentials

Configuring the Supabase Client

Step 3: Database Setup

Execute SQL Modules in Order

How to Execute SQL Scripts

Database Tables Overview

Step 4: Create Your First Admin User

Step 5: Development Server

Available Scripts

Step 6: Optional Features

Enable Push Notifications

Configure Real-time Subscriptions

Step 7: Verify Installation

Troubleshooting

Production Deployment

Next Steps