# ProInvoice — Installation Guide

**Audience:** First-time buyers, cPanel users, VPS/aaPanel users  
**Stack:** Laravel, MySQL, PHP  
**Includes:** Download instructions, hosting setup, installer wizard, cron, email overview, addons overview  

---

## Table of contents

1. [Introduction](#1-introduction)  
2. [Before you begin](#2-before-you-begin)  
3. [Downloading from CodeCanyon](#3-downloading-from-codecanyon)  
4. [Package structure — which ZIP to upload](#4-package-structure--which-zip-to-upload)  
5. [License key — quick pointer](#5-license-key--quick-pointer)  
6. [Installation on cPanel](#6-installation-on-cpanel)  
7. [Installation on VPS / aaPanel](#7-installation-on-vps--aapanel)  
8. [Web root, project root, and public directory](#8-web-root-project-root-and-public-directory)  
9. [Installer wizard (Stage 1–4)](#9-installer-wizard-stage-14)  
10. [After installation — admin login](#10-after-installation--admin-login)  
11. [Cron jobs / scheduler](#11-cron-jobs--scheduler)  
12. [Email configuration (overview)](#12-email-configuration-overview)  
13. [Addon installation (overview)](#13-addon-installation-overview)  
14. [Why this installer is beginner-friendly](#14-why-this-installer-is-beginner-friendly)  
15. [Recommended hosting environments](#15-recommended-hosting-environments)  
16. [Best practices after installation](#16-best-practices-after-installation)  
17. [Before going live checklist](#17-before-going-live-checklist)  

---

## 1. Introduction

This guide walks you from **purchase** to a **working admin login**. ProInvoice runs in a web browser. Your server stores the database and files; your team uses the **Admin Panel** to create invoices, track payments, and run reports.

**You do not need to know Laravel** to install the product. Follow the steps in order.

---

## 2. Before you begin

### 2.1 Server requirements (typical)

| Requirement | Guidance |
|-------------|----------|
| **PHP** | 8.2 or newer (confirm with your host or installer Stage 1) |
| **Database** | MySQL 5.7+ or MariaDB 10.3+ (MySQL-compatible) |
| **Web server** | Apache with `mod_rewrite`, or Nginx with URL rewriting |
| **Disk space** | Enough for the application plus uploads (logos, PDFs) |
| **SSL** | **Strongly recommended** for production (HTTPS) |

### 2.2 PHP extensions

Your host should provide common Laravel extensions. The **installer Stage 1** will highlight anything missing. Typical requirements include:

- `openssl`, `pdo`, `pdo_mysql`, `mbstring`, `tokenizer`, `xml`, `ctype`, `json`, `bcmath`, `fileinfo`, `curl`

> **Note:** If an extension shows red in Stage 1, open a ticket with your host and ask them to enable it for your PHP version.

### 2.3 Database

You need:

- A **database name**  
- A **database username** and **password**  
- The **database host** (often `localhost` on cPanel; sometimes `127.0.0.1` or a remote host on some clouds)  

### 2.4 SSL recommendation

Always use **HTTPS** in production to protect login credentials and customer data.

### 2.5 Cron job requirement

ProInvoice uses **scheduled tasks** for features such as:

- Billing **reminders** (due soon, overdue, quotation expiry)  
- **Recurring invoices** (if you use that feature)  
- Other **Laravel scheduler** jobs  

Without cron, the app may work, but **time-based automation will not run reliably**.

---

## 3. Downloading from CodeCanyon

### 3.1 Log in to Envato

1. Open your browser and go to **[codecanyon.net](https://codecanyon.net)**.  
2. Click **Sign In** and use your **Envato** account (the same account you used to purchase).  

[Insert Screenshot: CodeCanyon Sign In]

### 3.2 Open your downloads

1. After logging in, click your **profile icon** (top right).  
2. Choose **Downloads** (or **My Downloads**).  

[Insert Screenshot: Envato Downloads Menu]

### 3.3 Find ProInvoice

1. In the downloads list, locate **ProInvoice** (or the exact item title shown on CodeCanyon).  
2. Click the **Download** button next to the item.  

### 3.4 Choose the correct download type

You may see several options. Common ones:

| Download option | What it usually contains | When to use it |
|-----------------|-------------------------|----------------|
| **Installable / Main Files** (wording varies) | The **application ZIP** you upload to your server | **Use this for installation** |
| **All files & documentation** | Full package: installable + docs + extras | Use if you want everything in one download |
| **Documentation** | PDF or docs only | Reference only — **not** for uploading as the app |

> **Important:** For installation you need the **application files** (the Laravel project), not documentation-only ZIPs.

[Insert Screenshot: CodeCanyon Download Dropdown]

### 3.5 Save the file

Save the ZIP to your computer. You will upload it in the next sections.

---

## 4. Package structure — which ZIP to upload

After you extract the **full package** on your computer, you may see a structure similar to:

```text
product-package/
├── documentation/          ← Help files (read offline)
├── installable/            ← Often contains the main app ZIP
│   └── proinvoice.zip      ← Example name — yours may differ
├── addons/                 ← Optional addon packages (if included)
├── changelog.txt           ← Version notes
└── ...
```

### What each part means

- **`documentation/`** — User guides (may duplicate or extend the `/doc` folder).  
- **`installable/`** — Contains the **ZIP you upload to the server** (the actual web application).  
- **`addons/`** — Separate packages installed later from the admin panel (see Addon section).  

### Which file should you upload?

- Upload the **installable application ZIP** (the Laravel project archive provided by the author).  
- **Do not** upload only the outer “All files” folder without checking what is inside — always locate the **inner** installable archive if one is provided.  

> **Tip:** If you only have one ZIP and it contains folders like `app`, `public`, `composer.json`, that ZIP **is** the project — upload that.

---

## 5. License key — quick pointer

Before or during installation you will need an **activation license key** from the **author’s license portal**. That process uses your **Envato purchase code**.

**Full detail:** See **[LICENSE_GUIDE.md](LICENSE_GUIDE.md)**.

Short version:

1. Copy your **purchase code** from CodeCanyon.  
2. Visit the **license website URL** provided in the download or item description.  
3. Enter purchase code, **email**, and **domain**.  
4. Copy the **generated activation key** into **Installer Stage 3**.  

---

## 6. Installation on cPanel

### Step 1 — Log in to cPanel

1. Your hosting provider emails you a **cPanel URL**, username, and password.  
2. Open the URL and sign in.  

[Insert Screenshot: cPanel Login]

### Step 2 — Open File Manager

1. In cPanel, find **Files** → **File Manager**.  
2. Open the folder where your website should live:  
   - Main domain: often **`public_html`**  
   - Addon domain: the folder your host assigned  
   - Subfolder: e.g. `public_html/billing` if you want `yoursite.com/billing`  

[Insert Screenshot: cPanel File Manager]

### Step 3 — Upload the installable ZIP

1. Click **Upload**.  
2. Select your **application ZIP** from your computer.  
3. Wait until the upload reaches **100%**.  
4. Return to File Manager and **refresh** if needed.  

> **Warning:** Some hosts limit upload size. If upload fails, increase **PHP upload limits** in cPanel **MultiPHP INI Editor** or ask your host.

### Step 4 — Extract the ZIP

1. Right-click the ZIP → **Extract**.  
2. Confirm extraction.  

### Step 5 — Move files if they extracted into a subfolder

If you see `public_html/ProInvoice/app/...` instead of `public_html/app/...`:

1. Open the inner folder that contains `app`, `public`, `composer.json`.  
2. **Move all contents** up to `public_html` (or your target folder).  

You should end with `public` as a **subfolder** of the project, e.g. `public_html/public`.

### Step 6 — Point the domain to the `public` folder (critical)

Laravel serves the site from the **`public`** directory.

**Recommended approaches:**

- **Best:** Set your domain’s **document root** to `public_html/public` (if your host allows changing document root).  
- **Alternative:** Use the author’s recommended **.htaccess** redirect from `public_html` to `public` if documented for this product.  

> **Warning:** If the document root stays on `public_html` without pointing to `public`, you may see errors, exposed files, or broken CSS. See **Section 8** below.

### Step 7 — Create a MySQL database

1. In cPanel, open **MySQL® Databases**.  
2. Under **Create New Database**, enter a name → **Create Database**.  
3. Under **MySQL Users**, create a **username** and **strong password** → **Create User**.  
4. Under **Add User To Database**, select the user and database → **Add**.  
5. On the privileges screen, choose **ALL PRIVILEGES** → **Make Changes**.  

Write down:

- Database name (often prefixed, e.g. `cpuser_dbname`)  
- Database user  
- Password  
- Host (usually `localhost`)  

[Insert Screenshot: cPanel MySQL Databases]

### Step 8 — Set folder permissions (if needed)

If the installer reports **storage** or **bootstrap/cache** not writable:

- Folders `storage` and `bootstrap/cache` should be writable by the web server.  
- On cPanel, use **File Manager** → folder **Permissions** (e.g. `755` for folders; the author may suggest `775` on some hosts — follow installer messages).  

> **Tip:** Never set world-writable `777` unless your host explicitly requires it temporarily.

### Step 9 — Open the installer URL

In your browser, visit:

- `https://yourdomain.com`  
- or `https://yourdomain.com/subfolder` if installed in a subfolder  

You should see **Installer Stage 1**.  

[Insert Screenshot: Installer Stage 1 — cPanel context]

If you see a **403** or **404**, recheck **document root** and that files uploaded completely.

---

## 7. Installation on VPS / aaPanel

These steps are typical for **aaPanel**; adapt names if you use plain Ubuntu + Nginx.

### Step 1 — Log in to aaPanel

1. Open your panel URL (e.g. `https://your-server-ip:port`).  
2. Sign in with your panel credentials.  

### Step 2 — Create a website

1. Go to **Website** → **Add site**.  
2. Enter your **domain**.  
3. Choose **PHP** site type if prompted.  
4. Note the **root path** aaPanel created (e.g. `/www/wwwroot/yourdomain.com`).  

### Step 3 — Upload the ZIP

1. Open **Files** for that site (or use SFTP with FileZilla).  
2. Upload the **installable ZIP** into the site root (or a temporary folder).  
3. Extract it.  

### Step 4 — Set the website root to `public`

**This is the most important step on VPS.**

1. In aaPanel, open the site → **Settings** (or **Document Root**).  
2. Change the root from:

   - `/www/wwwroot/yourdomain.com`  

   to:

   - `/www/wwwroot/yourdomain.com/public`  

3. Save.  

[Insert Screenshot: aaPanel Document Root pointing to /public]

### Step 5 — Create the database

1. In aaPanel, open **Databases** → **Add database**.  
2. Set database name, user, and password.  
3. Record host (often `localhost` or `127.0.0.1`).  

### Step 6 — PHP version and limits

1. Install **PHP 8.2+** from the panel if not installed.  
2. Assign that PHP version to your site.  
3. Increase limits if uploads fail:

   - `upload_max_filesize`  
   - `post_max_size`  
   - `max_execution_time`  
   - `memory_limit` (often **256M** or higher for composer-style operations if you run CLI on server)  

[Insert Screenshot: aaPanel PHP Settings]

### Step 7 — Permissions

Ensure `storage` and `bootstrap/cache` are writable by the web user (e.g. `www`):

- Typical folders: `755` or `775` as advised by installer errors.

### Step 8 — Open the installer

Visit `https://yourdomain.com` and continue with **Section 9**.

---

## 8. Web root, project root, and public directory

| Term | Meaning |
|------|---------|
| **Project root** | Where `composer.json`, `app`, `config`, and `public` folders live |
| **`public` directory** | The **only** folder that should be directly exposed to the internet |
| **Web root / document root** | The folder your web server uses as the site’s entry point — should be **`public`** |

**Common mistake:** Setting document root to the **project root** instead of **`public`**. That can break routing and security.

---

## 9. Installer wizard (Stage 1–4)

### Stage 1 — Welcome & system requirements

**Purpose:** Confirms PHP version, extensions, and writable paths before you continue.

**What you see:**

- Green checks = OK  
- Red items = must fix (enable extension or fix permissions)  

**Typical checks:**

- PHP version  
- Required extensions  
- Writable `storage` and `bootstrap/cache`  

> **Tip:** Fix all red items before proceeding — Stage 2 will not succeed if the server cannot write files or connect properly later.

[Insert Screenshot: Installer Stage 1 Requirements]

Click **Next** when everything passes.

---

### Stage 2 — Database configuration

**Purpose:** Connect the software to MySQL.

**Fields you will enter:**

| Field | Typical value | Common mistakes |
|-------|---------------|-----------------|
| **Host** | `localhost` or `127.0.0.1` | Using `localhost` when host requires a socket path — ask host |
| **Port** | `3306` | Wrong port on custom setups |
| **Database name** | From cPanel / aaPanel | Typo or wrong prefix |
| **Username** | Database user | Copy-paste errors |
| **Password** | Database password | Extra spaces when pasting |

**Test connection:** Use the installer’s **Test** button if available. If connection fails:

- Verify user is **assigned** to the database with **ALL PRIVILEGES**.  
- Confirm database **exists**.  
- Try `127.0.0.1` instead of `localhost` (or vice versa) per host documentation.  

[Insert Screenshot: Installer Stage 2 Database]

---

### Stage 3 — License activation

**Purpose:** Unlocks the product using your **activation key** from the author’s license portal.

**What you enter:**

- **Activation license key** (generated on the author’s website — **not** always the raw Envato code)  
- **Domain** (must match how you access the site — the author’s system may validate the domain binding)  

**When verification succeeds:** You can continue to Stage 4 or finish.

**When it fails:** See **[LICENSE_GUIDE.md](LICENSE_GUIDE.md)** and **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)**.

> **Remember:** Your **Envato purchase code** proves you bought the item. The **activation key** is what the installer accepts.

[Insert Screenshot: Installer Stage 3 License]

---

### Stage 4 — Demo data import (optional)

**Purpose:** Load sample customers, invoices, or settings so you can explore faster.

**When to import demo data:**

- **Yes** — Training, demos, or evaluating reports.  
- **No** — You are going live immediately and want a clean database.  

**After import:** You can delete demo records later from the admin panel (or reinstall on a fresh database — only if acceptable for your situation).

**If you skip:** The system is empty; you create customers and invoices yourself.

[Insert Screenshot: Installer Stage 4 Demo Data]

---

### Finish installation

1. You should see a **success** message.  
2. Note the **admin login URL** (usually your domain + `/login` or `/admin/login` depending on build — follow on-screen text).  
3. **Remove or secure** the installer if the product displays a warning (follow author instructions).  

**Next steps:**

1. Log in as admin.  
2. Change password.  
3. Open **Settings** and enter company details.  
4. Configure **SMTP** and **cron**.  

---

## 10. After installation — admin login

1. Open the URL shown after install (example patterns):  
   - `https://yourdomain.com/login`  
   - `https://yourdomain.com/admin/login`  
2. Enter the **admin email** and **password** created or shown during installation.  
3. After login, go to **Profile** or **Users** and **change your password**.  

> **Security:** Change the default or generated password **before** sharing access.

[Insert Screenshot: Admin Login Page]

Full daily usage: **[USER_MANUAL.md](USER_MANUAL.md)**.

---

## 11. Cron jobs / scheduler

### Why cron is needed

Laravel’s scheduler runs **every minute** via one system cron entry. That scheduler then runs internal tasks (reminders, recurring billing, etc.) at the right times.

### cPanel cron example

1. cPanel → **Cron Jobs**.  
2. Under **Add New Cron Job**, choose **Every Minute** (`* * * * *`).  
3. Command (adjust path to your project):

```bash
cd /home/USERNAME/public_html && php artisan schedule:run >> /dev/null 2>&1
```

If your project lives in a subfolder:

```bash
cd /home/USERNAME/public_html/billing && php artisan schedule:run >> /dev/null 2>&1
```

> **Note:** Replace `USERNAME` and path with your real cPanel home path. Some hosts show the path in cPanel sidebar as **Home Directory**.

### VPS / aaPanel cron example

```bash
* * * * * cd /www/wwwroot/yourdomain.com && php artisan schedule:run >> /dev/null 2>&1
```

### Queue workers (if you use queues)

If the product is set to send email or jobs via **queue**, you may also need:

```bash
php artisan queue:work --stop-when-empty
```

or a **supervisor** / long-running worker setup on VPS. Check **USER_MANUAL.md** → Reminder System for **queue** vs **instant** email mode.

### How to verify cron works

- After a few minutes, check **Reminder Logs** or **scheduled task** evidence in the admin panel (if available).  
- Check server logs if the author documents log locations.  

More detail: **[USER_MANUAL.md](USER_MANUAL.md)** and **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)**.

---

## 12. Email configuration (overview)

1. Admin → **Settings** → **Email** (wording may vary).  
2. Enter **SMTP host, port, encryption, username, password**.  
3. Set **From address** and **From name**.  
4. Send a **test email** if the feature exists.  

**Full guide:** **[USER_MANUAL.md](USER_MANUAL.md)** → Email Configuration.

---

## 13. Addon installation (overview)

1. Obtain addon ZIP from the author (if purchased separately).  
2. Admin → **Addon Manager** (if present).  
3. **Upload** or **install** per on-screen steps.  
4. **Activate** and enter **addon license** if required.  

**Full guide:** **[USER_MANUAL.md](USER_MANUAL.md)** → Addon Manager.

---

## 14. Why this installer is beginner-friendly

- Requirements are checked **before** database setup.  
- You do not run SQL scripts by hand for a standard install.  
- Demo data is **optional**.  
- Error messages usually point to **permissions**, **PHP extensions**, or **wrong database credentials**.  

---

## 15. Recommended hosting environments

- **cPanel shared** — Best when document root can be set to `/public` or equivalent.  
- **cPanel VPS** — Ideal balance of GUI and control.  
- **aaPanel** — Popular on VPS; set site root to `/public`.  
- **Managed WordPress-only hosts** — Often **not** suitable if they block custom PHP apps or cron.  

---

## 16. Best practices after installation

1. Strong **unique** admin password  
2. **HTTPS** everywhere  
3. **Backups** (database + files) on a schedule  
4. **SMTP** configured and tested  
5. **Cron** enabled  
6. Review **Roles & Permissions** before adding staff users  
7. Read **SECURITY.md**  

---

## 17. Before going live checklist

- [ ] HTTPS enabled  
- [ ] Company profile completed  
- [ ] Tax and currency correct  
- [ ] Invoice numbering matches your business  
- [ ] SMTP tested  
- [ ] Cron running  
- [ ] License valid for production domain  
- [ ] Demo data removed or understood  
- [ ] Staff accounts use least privilege  

---

## Need help?

- **License issues:** [LICENSE_GUIDE.md](LICENSE_GUIDE.md)  
- **Errors:** [TROUBLESHOOTING.md](TROUBLESHOOTING.md)  
- **Usage:** [USER_MANUAL.md](USER_MANUAL.md)  
- **Quick answers:** [FAQ.md](FAQ.md)  

---

*End of Installation Guide*
