# Dubai Real Estate CRM — cPanel installation

This package has been converted from Manus hosting to a standalone cPanel Node.js application.
It uses MySQL/MariaDB and local private file storage. Manus OAuth and Manus storage are not required.

## Requirements

- cPanel with **Setup Node.js App / Node.js Selector** (CloudLinux/Passenger or equivalent)
- Node.js **20.19+**; Node.js 22 is recommended
- MySQL or MariaDB database
- HTTPS/SSL on the CRM domain or subdomain

> If your cPanel account does not offer Node.js applications, this CRM cannot run as a normal PHP-only site. Ask the hosting provider to enable Node.js or use a VPS.

## 1. Create the MySQL database

In **cPanel → MySQL Databases**:

1. Create a database, for example `account_crm`.
2. Create a database user, for example `account_crmuser`.
3. Add the user to the database with **ALL PRIVILEGES**.
4. Open **phpMyAdmin**, select the new database, choose **Import**, and import `database.sql` from this package.

The SQL file creates the complete CRM schema. You do not need to run the Drizzle migration files for a new installation.

## 2. Upload the application

Recommended application root:

`/home/YOUR_CPANEL_USER/dubai-crm`

Upload/extract all files from this ZIP into that directory. The application does not need to live directly inside `public_html` when cPanel's Node.js App feature maps the domain/subdomain to it.

Make sure `data/uploads` exists and is writable by your cPanel user. Normal permissions such as `755` for directories are usually sufficient.

## 3. Configure environment variables

In **cPanel → Setup Node.js App**, add these environment variables:

- `NODE_ENV` = `production`
- `DATABASE_URL` = `mysql://FULL_DB_USER:DB_PASSWORD@localhost/FULL_DB_NAME` (URL-encode special characters in the password)
- `JWT_SECRET` = a long random secret, at least 32 characters (you can generate one with `node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"`)
- `ADMIN_USERNAME` = your CRM username
- `ADMIN_PASSWORD` = your strong CRM password
- `ADMIN_NAME` = display name shown in the CRM
- `ADMIN_EMAIL` = optional
- `APP_ID` = `dubai-realestate-crm`
- `LOCAL_ADMIN_OPEN_ID` = `local_admin`

Do **not** manually set `PORT`; cPanel normally supplies it to the Node.js application.

You may use `.env.example` as a reference. cPanel environment variables are preferred over keeping real passwords in a file.

## 4. Create the Node.js application

In **Setup Node.js App** use:

- Node.js version: **22.x** if available, otherwise a compatible 20.19+ version
- Application mode: `Production`
- Application root: your extracted CRM folder, e.g. `dubai-crm`
- Application URL: preferably the root of a dedicated domain/subdomain (for example `crm.example.com`), not a nested `/crm` path
- Application startup file: `app.js`

Create/save the application.

## 5. Install production packages

Use cPanel Terminal while the Node environment is active, or the command cPanel provides for entering the app's virtual environment.

From the application root run:

```bash
npm install --omit=dev
npm run build
```

The build command creates the production `dist` folder used by `app.js`. The build tools required for this are included as production dependencies specifically for cPanel deployment.

Before restarting, you can verify the configuration with:

```bash
npm run cpanel:check
```

It checks the required environment variables, MySQL connectivity/schema presence, and upload-directory write permissions without printing your passwords.

Then restart the Node.js application in cPanel. If you later edit the TypeScript/React source, run `npm run build` again before restarting.

## 6. Restart and login

Restart the application from **Setup Node.js App** and open the application URL.
You will be sent to `/login`. Use the `ADMIN_USERNAME` and `ADMIN_PASSWORD` values you configured.

The first successful login automatically creates/updates the local administrator row in the `users` table.

## File uploads

Uploaded client documents, agreements, contracts and receipts are stored under:

`data/uploads/`

They are not placed in the public frontend folder. File routes require an authenticated CRM session.
Back up both the **MySQL database** and the **data/uploads** directory.

For large uploads, your hosting provider may also enforce request-size/time limits outside Node.js. If very large documents fail while smaller files work, ask the host to increase the proxy/Passenger upload limit.

## PDF payment reports

Payment-report PDFs use Puppeteer. By default Puppeteer uses its installed Chrome/Chromium. If the host provides Chromium separately and PDF generation fails, set:

`PUPPETEER_EXECUTABLE_PATH=/path/to/chromium`

The host can tell you the correct executable path if needed.

## Backup checklist

Back up these two things together:

1. MySQL database
2. `data/uploads/`

Without both, database document records and their actual uploaded files can become out of sync.