# QuickEcommerce — Automated Store Provisioning: Setup Guide

This is Option A: automating your current "copy the code, make a database"
process. Every piece below has been built and tested against a real copy of
your database and file system before being handed to you — including two
real bugs (a MySQL statement-ordering issue and a SQL-comment parsing bug)
that were found and fixed by actually running the code, not just reading it.

---

## 1. What you're setting up

```
quickecommerce.co/                    <- your main site, NOT a store
├── public/
│   ├── signup.html                   <- the customer-facing form
│   ├── signup-handler.php            <- processes signups, calls the engine
│   └── check-subdomain.php           <- live "is this name available" check
├── lib/
│   ├── CpanelApi.php                 <- talks to cPanel's own API
│   ├── StoreProvisioner.php          <- the actual engine
│   └── config.template.ini           <- per-store config template
├── config/
│   ├── master-db.php                 <- YOU fill in real credentials
│   ├── cpanel-config.php             <- YOU fill in your cPanel token
│   └── provisioner-config.php        <- YOU fill in paths/domain
└── sql/
    ├── master-schema.sql             <- run ONCE, sets up tracking DB
    ├── base-schema-raw.sql           <- imported into every NEW store
    ├── feature-additions.sql         <- imported into every NEW store
    └── default-data.sql              <- imported into every NEW store
```

`quickecommerce.co` itself is just a normal PHP site (any hosting works for
it) — it doesn't run QuickCatalog. Its only job is showing the signup form
and calling the provisioning engine, which then creates a brand new,
completely separate QuickCatalog installation for each customer.

---

## 2. One-time setup (do this once, not per store)

### 2a. Generate your cPanel API Token

1. Log into cPanel (your host gives you a login URL, often
   `https://yourdomain.com:2083`).
2. **Security → Manage API Tokens → Create**.
3. Name it something like `quickecommerce-provisioner`. No expiry, or a long
   one — you can revoke it instantly later if needed.
4. **Copy the token immediately** — cPanel only shows it once.
5. Also note your **cPanel username** (top-right of the cPanel dashboard)
   and the **host** shown in your browser's address bar right now (usually
   your main domain, sometimes a shared server hostname your host gave you
   — check your welcome email from them if unsure).

Fill these three values into `config/cpanel-config.php`.

### 2b. Find your cPanel home directory

In cPanel, open **File Manager**. The folder ABOVE `public_html` is your
home directory — usually `/home/yourusername`. Put this in
`QC_CPANEL_HOME_DIR` inside `config/provisioner-config.php`.

### 2c. Prepare your "template" codebase

This is the clean, current QuickCatalog code — including everything we've
built together (Brands, PDF Brochure, Stock Available, etc.) — that gets
copied into every new store.

1. Upload a clean copy of your QuickCatalog codebase somewhere **outside**
   `public_html` (so it's never itself web-accessible) — e.g.
   `/home/yourusername/quickcatalog-template/`.
2. Make sure it does **NOT** contain a `config.ini` with real credentials —
   the provisioner writes a fresh one per store automatically. If one
   exists in the template, it's fine; it's excluded from every copy.
3. Update `QC_TEMPLATE_PATH` in `config/provisioner-config.php` to point here.

**This is the single most important habit to build going forward:**
whenever you fix a bug or add a feature (exactly like everything from this
week), update this template folder. Every store created *after* that point
gets the improvement automatically. Stores created *before* still need the
file copied to them by hand — that per-store update gap is the real
trade-off of Option A, and the reason Option B (one shared codebase for
every store) is worth revisiting once you're past the early stage.

### 2d. Create the master tracking database

In cPanel → MySQL Databases, create a database and a user for it (same as
you'd do for any store, just this one time), then run `sql/master-schema.sql`
against it via phpMyAdmin. Fill the real credentials into
`config/master-db.php`.

### 2e. Wildcard DNS + SSL

For `anything.quickecommerce.co` to work, you need:
- A **wildcard DNS record**: `*.quickecommerce.co` → your server's IP
  (ask your host, or add it yourself if you manage DNS).
- A **wildcard SSL certificate** covering `*.quickecommerce.co`. Most cPanel
  hosts offer free wildcard Let's Encrypt certificates via **SSL/TLS →
  Manage SSL Sites**, or AutoSSL if your host has it configured for
  wildcards — ask your host if you don't see the option, since not all
  shared-hosting AutoSSL setups support wildcards by default.

### 2f. Upload everything

Upload `public/`, `lib/`, `config/`, and `sql/` to your `quickecommerce.co`
hosting (`public/` should map to your document root; the others can sit
one level above it, outside the web-accessible folder, for safety).

---

## 3. Test it once before going live

1. Open `signup.html` in a browser.
2. Fill in the form with a throwaway test store name.
3. Watch it work — a real subdomain, database, and store should exist
   within about 30 seconds.
4. Log into the new store's `/admin` with the email/password you just set.
5. **Delete the test store manually** afterward (cPanel → MySQL Databases
   to drop the database, File Manager to delete the folder, and delete its
   row from `quickecommerce_master.stores`) — there's no "delete" button
   built yet; see the roadmap below.

---

## 4. Security checklist before real customers use this

- [ ] **Rate limiting.** Right now, `signup-handler.php` has no limit on how
      often one person can submit the form — add one before going live
      (e.g. max 3 signups per IP per hour), or this endpoint can be used to
      spam-create databases and eat your hosting quota. A simple table
      logging attempts by IP, checked before provisioning starts, is enough.
- [ ] **CAPTCHA** on the signup form (Google reCAPTCHA or hCaptcha) — cheap
      insurance against bots.
- [ ] **Email verification.** Right now a store goes live immediately with
      any email address, verified or not. Consider sending a confirmation
      link before the store is usable, or at least before it counts toward
      a "real" customer.
- [ ] **`config/` folder is not web-accessible.** Test this directly:
      visit `https://quickecommerce.co/config/cpanel-config.php` in a
      browser — it must NOT display your token. If it does, move `config/`
      outside your document root, or add a `.htaccess` with `deny from all`
      inside that folder.
- [ ] **Database quota.** Shared cPanel plans often cap the number of MySQL
      databases you can create (sometimes unlimited, sometimes not) — check
      **MySQL Databases** in cPanel for a "you have used X of Y" indicator
      before you're relying on this at scale.

---

## 5. What's deliberately NOT built yet (roadmap)

- **Demo data seeding by business type.** The signup form already asks
  "what do you sell?" and stores the answer, but every new store currently
  starts completely empty (no sample products/categories). Wiring in a
  seed pack per business type (matching the same idea as your existing
  Lakshmi Boutique / herbal-store demo templates) is a natural next step.
- **Welcome email.** `signup-handler.php` has a clearly marked `// TODO`
  where this belongs — currently the browser just redirects straight to
  the new admin panel with no email sent.
- **Store deletion / suspension UI.** The master database already tracks
  `status` (`active`, `suspended`, `expired`, `deleted`) and `trial_ends_at`,
  but nothing acts on them yet — no automatic trial-expiry job, no admin
  dashboard to browse/manage all stores. The data model is ready; the UI
  and a scheduled task (cPanel Cron Job) to enforce expiry are not built.
- **A real admin dashboard** for you to see all stores, search by owner
  email, and manually suspend/extend/delete — right now that's all direct
  database/phpMyAdmin work.

---

## 6. If something goes wrong for a customer mid-signup

Check `quickecommerce_master.provisioning_log`, filtered by their
subdomain — every step is recorded there with `ok` or `failed` and the
exact error message, in the order it happened. That table exists
specifically so a failed signup is never a mystery.
