# MakeLeads.us — Fresh Install Guide (Namecheap cPanel)

This is a complete, from-scratch install. Follow every step in order — skipping
the Node.js App setup step is the most common cause of a broken deploy.

## What you're installing

A zero-dependency Node.js B2B lead platform: user signup/login, lead browsing
and purchasing with credits, marketing campaigns (email/SMS/voicemail), a
sales pipeline, analytics, and a full admin panel at `/admin` for managing
users, leads, CSV/XLSX data import, and revenue.

No `npm install` is required — the app uses only Node's built-in modules.

---

## Step 1 — Upload the files

1. Log into **cPanel**.
2. Open **File Manager**.
3. Navigate to (or create) the directory where the site should live —
   typically `public_html` for the main domain, or
   `public_html/yoursubdomain` if MakeLeads is on a subdomain.
4. Upload `makeleads-deploy.zip` into that directory.
5. Right-click the zip → **Extract**. This unpacks everything into the
   current directory (you should now see `server.js`, `app.js`, `public/`,
   `admin/`, `server/`, etc. directly inside it).
6. Delete the zip file afterward (optional, just keeps things tidy).

## Step 2 — Set environment variables

1. Still in File Manager, copy `.env.example` to a new file named `.env`
   (right-click → Copy, rename the copy).
2. Edit `.env` and set at minimum:
   - `JWT_SECRET` — replace with a long random string (this signs login
     tokens; treat it like a password). You can generate one by running
     `openssl rand -hex 32` in cPanel's Terminal, or just mash the keyboard
     for 40+ characters.
3. The `SENDGRID_*`, `TWILIO_*`, and `SLYBROADCAST_*` keys are optional. If
   you leave them blank, those features run in **simulation mode** — emails,
   texts, and voicemails are logged instead of actually sent, so the rest of
   the app works fully without those accounts. Add real keys later when
   you're ready to send live campaigns.
4. **Stripe payments:** set `STRIPE_SECRET_KEY` and `STRIPE_PUBLISHABLE_KEY`
   (from https://dashboard.stripe.com/apikeys) and set `APP_URL` to your
   site's public URL (e.g. `https://makeleads.us`, no trailing slash) — the
   Stripe checkout redirects back to this address. With `sk_test_` keys, use
   Stripe's test card `4242 4242 4242 4242` (any future expiry / any CVC) to
   test purchases end-to-end without real money. Swap in `sk_live_` keys when
   you're ready to charge real cards.
   - `STRIPE_WEBHOOK_SECRET` is optional. Without it, purchases are fulfilled
     when the buyer lands back on the success page (verified against Stripe's
     API). For production it's still recommended to also add a webhook
     (Stripe dashboard → Webhooks → endpoint `https://yourdomain.com/api/stripe/webhook`,
     event `checkout.session.completed`) so credits are granted even if the
     buyer closes the tab before returning.
   - If you leave the Stripe keys blank entirely, purchases run in simulation
     mode (instantly granted, nothing charged) — fine for testing, unsafe for
     production.

## Step 3 — Create the Node.js Application in cPanel

This is the step that's easy to miss, and the site will 404, 500, or show a
directory listing without it.

1. In cPanel, find **Setup Node.js App** (sometimes listed as "Node.js
   Selector").
2. Click **Create Application**.
3. Fill in:
   - **Node.js version**: pick the newest available (18.x or 20.x both work)
   - **Application mode**: Production
   - **Application root**: the folder you extracted into (e.g.
     `public_html` or `public_html/yoursubdomain`)
   - **Application URL**: the domain/subdomain this should serve
   - **Application startup file**: `app.js`
4. Click **Create**. cPanel will generate the correct `.htaccess` for you
   automatically — this overwrites the placeholder one from the zip with the
   real Node path for your account, which is exactly what you want.
5. Click **Start App** (or **Restart** if it auto-started).

## Step 4 — Verify it's running

1. Visit your domain. You should see the MakeLeads homepage, not a
   directory listing or an error page.
2. Visit `yourdomain.com/admin`. You should see a separate admin login
   screen.
3. Log in with the default admin account:
   - **Email**: `admin@makeleads.us`
   - **Password**: `MakeLeads2024!`
4. **Immediately change this password** — go to admin **Settings** →
   change password, once you're in.

The database file is created automatically on the very first request (not
on startup), at `data/db.json` inside your application root, seeded with
510 sample leads across 5 categories so the platform isn't empty on day one.

## Step 5 — Import your own lead data (optional)

From the admin panel → **Upload Data**:
1. Drag in a `.csv` or `.xlsx` file.
2. Pick a default category (used as a fallback if a row doesn't specify
   one).
3. Click import. The system auto-detects column headers (even if your
   sheet has a few junk rows above the real header row), maps dozens of
   common column-name variants (e.g. `company`/`business_name`/`dba` all
   map to the same field), cleans phone numbers and emails, and reports
   any rows it had to skip with a reason.

## Troubleshooting

**"Index of /" or directory listing instead of the site**
The `.htaccess` doesn't have the right Passenger paths. Go back to **Setup
Node.js App**, click the edit (pencil) icon on your app, and hit **Save**
without changing anything — this forces cPanel to regenerate `.htaccess`.
Then **Restart**.

**Error 508 — Resource Limit Reached**
The app likely crash-looped on startup before. Wait 15–30 minutes for
Namecheap to lift the temporary limit, then restart the app. This codebase
defers all database setup to the first incoming request (not app startup)
specifically to avoid this, so it shouldn't recur — but if you edit
`server.js`, avoid adding heavy work back to module-load time.

**Admin login fails with "Invalid credentials"**
This means `data/db.json` already exists with a different admin account —
most likely from an earlier install attempt. Either log in with whatever
admin email/password was set then, or delete `data/db.json` via File
Manager and reload the site once to regenerate it with the default admin.

**502/503 errors**
Usually means the Node app isn't running. Go to **Setup Node.js App** and
check the app's status; click **Restart**. Check the app's log output
(available from the same cPanel screen) for the actual error if it keeps
failing.

---

## Updating the site later

Whenever you have new code to deploy:
1. Upload the new zip via File Manager and extract (overwrite existing
   files) — this will NOT touch `data/db.json` or `.env`, those are your
   live data.
2. Go to **Setup Node.js App** → **Restart** your app.

That's the entire update process — no rebuild step, no dependency
installs.