Installation

Complete installation guide for MLM CMMS - from environment setup to production deployment

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

1. Clone the Repository

   git clone https://github.com/EdgarJr30/cilm_easy_mant.git
   cd cilm_easy_mant
   
2. 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
3. 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

1. Create Supabase Project

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

   1. Navigate to Settings → API in your Supabase dashboard
   2. Copy the Project URL (use as VITE_SUPABASE_URL)
   3. Copy the anon/public key (use as VITE_SUPABASE_ANON_KEY)
3. Get Service Role Key (For Database Setup)

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

   1. In Settings → API, copy the service_role key
   2. Store this securely - it bypasses Row Level Security
   3. 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:

1. Core Infrastructure (00-05)

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

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

   6. 06_views.sql - Database views for simplified queries
   7. 07_indexes.sql - Performance indexes
3. Security (08-10)

   8. 08_rls.sql - Enable Row Level Security
   9. 09_policies.sql - RLS policies for data access control
   10. 10_seed_admin_permissions.sql - Initial admin permissions
4. Bootstrap and Features (11-14)

   11. 11_seed_bootstrap.sql - Initial data and default roles
   12. 12_updates.sql - Schema updates and migrations
   13. 13_realtime.sql - Real-time subscriptions configuration
   14. 14_storage.sql - Storage buckets and policies
5. Advanced Features (15-16)

   15. 15_grants_auth.sql - Authentication grants
   16. 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:

Supabase Dashboard

1. Go to your Supabase project
2. Navigate to SQL Editor
3. Click "New Query"
4. Copy and paste each script content
5. Click "Run" to execute
6. 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:

Development Mode

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:

1. Generate VAPID Keys

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

   This outputs a public and private key pair.

2. 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:[e-mail])
3. Deploy Edge Function

   npx supabase functions deploy send-push-from-outbox \
     --project-ref your-project-ref
   
4. 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:

1. Go to Database → Replication in Supabase dashboard
2. Enable replication for:
   • notification_deliveries
   • ticket_comments
   • tickets
3. 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:

1. Test Authentication

   1. Navigate to /login
   2. Sign in with your admin user
   3. Verify you’re redirected to /inicio
2. Check Permissions

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

3. Create Test Ticket

   1. Go to /crear-ticket
   2. Fill out the form and submit
   3. Check /solicitudes to see the request
   4. Accept it and verify it appears in /ordenes_trabajo
4. 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.