# 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.