# cPanel: sync from Git, zero Composer / npm / SSH

This repo is meant to run after a **plain Git pull** (or cPanel “Git Version Control” deploy). The server never runs Composer, npm, or Artisan.

## What is already in Git (you must push these from your dev machine)

| Piece | Why |
|--------|-----|
| **`vendor/`** | PHP dependencies (`composer install --no-dev` locally, then commit). |
| **`public/build/`** | Vite output (`npm run build` locally, then commit). |
| **`database/database.sqlite`** | Empty schema + migration history for SQLite mode (no DB import). |

When you change PHP packages or migrations, refresh those artifacts locally and push again.

---

## One-time setup in cPanel

1. **Document root** must be the Laravel **`public/`** folder (not the project root).
2. **Environment file**
   - In **File Manager**, go to the project root, copy **`.env.example`** → **`.env`**.
   - Edit **`.env`**: set **`APP_URL`** to your real URL (https).
   - **`APP_KEY`**: leave empty if **`.env` is writable** by the PHP user (often **644** or **664**). The app writes a key on the first request. If your host blocks writes, generate a key on your Mac with `php artisan key:generate --show` and paste into `.env`.
3. **Database — choose one**
   - **SQLite (simplest):** keep `DB_CONNECTION=sqlite` and leave `DB_DATABASE` commented. Ensure **`database/`** is writable (775) so SQLite can grow.
   - **MySQL:** in cPanel create a database and user. In **phpMyAdmin**, select that database → **Import** → upload **`database/schema/mysql-baseline.sql`**. In **`.env`**, set `DB_CONNECTION=mysql` and the host/name/user/password cPanel shows (often host is `localhost` or `127.0.0.1`).
4. **Writable directories:** **`storage/`** and **`bootstrap/cache/`** should be writable by the web server (775 is typical). Fix via File Manager if logs or views fail.

After that, opening the site should work. Register the first user at **`/register`**.

---

## Install via SSH (zip upload + MySQL)

Use this when the site does not work after unzip alone (wrong document root, permissions, PHP CLI version, or database not loaded). Replace paths and database names with yours.

### 0) Use PHP 8.4 in SSH (cPanel)

Laravel 13 needs **PHP ≥ 8.4** for both the browser and **`php artisan`**. On cPanel, SSH often defaults to an older `php`:

```bash
export PATH="/opt/cpanel/ea-php84/root/usr/bin:$PATH"
php -v   # must show 8.4.x
```

Add that `export` to `~/.bashrc` if you use SSH often.

### 1) Go to the app root (not `public/`)

```bash
cd ~/path/to/collabs-laravel   # folder that contains artisan, app/, vendor/
```

### 2) Environment

```bash
test -f .env || cp .env.example .env
```

Edit **`.env`**: set **`APP_URL`**, **`APP_DEBUG=false`**, and MySQL (comment out the SQLite block):

```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_cpanel_database
DB_USERNAME=your_cpanel_user
DB_PASSWORD=your_password
```

cPanel often shows the host as **`localhost`**; use exactly what **MySQL® Databases** lists.

### 3) Application key

```bash
php artisan key:generate --force
```

(If **`.env`** is not writable for the web user, the first HTTP request can still fail until this is set.)

### 4) Database — pick **one** method

**A) Import the shipped baseline (matches “no Artisan migrate on server”):**

```bash
mysql -h 127.0.0.1 -u your_cpanel_user -p your_cpanel_database < database/schema/mysql-baseline.sql
```

Enter the MySQL password when prompted. Do **not** run **`php artisan migrate`** afterward on the same database (the **`migrations`** table is already filled).

**B) Empty database + Artisan migrations (if you prefer migrate):**

Use a **new empty** database only, then:

```bash
php artisan migrate --force
```

### 5) Permissions

The web server user must write **`storage/`** and **`bootstrap/cache/`**:

```bash
chmod -R ug+rwx storage bootstrap/cache
```

On many shared hosts the account user owns the files; **`775`** on those directories is enough. If errors persist, ask the host which user runs PHP (sometimes you need **`chown`** only they can apply).

### 6) Clear stale caches (safe after moving or editing `.env`)

```bash
php artisan config:clear
php artisan cache:clear
php artisan view:clear
```

Optional production tuning (run only when **`.env`** is final):

```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

### 7) Web server document root

In cPanel, the domain’s **document root** must be **`.../collabs-laravel/public`**, not the project root. If it points at the wrong folder you get 404, wrong document, or blank pages.

### 8) If `vendor/` is missing or incomplete

From the project root, with PHP 8.4 first in **`PATH`**:

```bash
php ~/composer.phar install --no-dev --optimize-autoloader --no-interaction
```

(Install **`composer.phar`** as in the section below if needed.)

---

## Every deploy

Only **sync Git** (pull / deploy hook). No shell commands required.

If you changed **Composer** or **migrations** since last deploy, commit and push from dev first:

```bash
composer install --no-dev --optimize-autoloader
# SQLite baseline (optional if you ship sqlite):
rm -f database/database.sqlite && touch database/database.sqlite && php artisan migrate:fresh --force
npm run build
git add composer.lock vendor public/build database/database.sqlite database/schema/mysql-baseline.sql
git commit -m "Deploy artifacts"
git push
```

When migrations change, also update **`database/schema/mysql-baseline.sql`** (adjust SQL to match migrations, or export from a local MySQL after `migrate`).

---

## Limitations without SSH/cron

- **Queue workers** and **scheduler** (`collabs:push-reminders`) will not run unless your host provides another way to run PHP on a schedule. Push reminders and queued mail need a worker elsewhere or a host feature.

---

## PHP 8.4 on the site but SSH `php` is 8.3 (Composer + `artisan`)

MultiPHP sets **PHP 8.4 for Apache/LiteSpeed**, but SSH often still runs **`php` → 8.3**. This project’s `vendor/` includes Composer’s **platform check**, which runs as soon as PHP loads `vendor/autoload.php`. So **`php artisan …` with 8.3** fails with “dependencies require PHP >= 8.4” even though the site uses 8.4.

### 1. Put PHP 8.4 first in your SSH session (fixes `artisan`)

Run once per SSH login, or add to `~/.bashrc`:

```bash
export PATH="/opt/cpanel/ea-php84/root/usr/bin:$PATH"
php -v   # must show 8.4.x
php artisan key:generate --show
```

### 2. Install Composer as `composer.phar` (when `composer` is not in PATH)

If `command -v composer` prints nothing, **`php $(command -v composer) install`** becomes **`php install`** → error *Could not open input file: install*. Install Composer into your home directory:

```bash
export PATH="/opt/cpanel/ea-php84/root/usr/bin:$PATH"
cd ~
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --install-dir="$HOME" --filename=composer.phar
php -r "unlink('composer-setup.php');"
php ~/composer.phar --version
```

Then in the project:

```bash
cd ~/collabs-laravel   # your path
export PATH="/opt/cpanel/ea-php84/root/usr/bin:$PATH"
php ~/composer.phar install --no-dev
```

### 3. If a global `composer` exists but still fails

A **`/usr/local/bin/composer`** script may call **`#!/usr/bin/env php`** (still 8.3). Prefer **`php ~/composer.phar`** with PATH including **ea-php84** as above, not `php $(which composer)`.

This stack (**Symfony 8**) needs **PHP 8.4+** for CLI and web.

---

## HTTP 500

- Missing **`public/build/manifest.json`** → run **`npm run build`** locally and commit **`public/build/`**.
- Missing **`vendor/`** in the deployed tree → commit **`vendor/`** from **`composer install --no-dev`**.
- **`APP_KEY`** missing and **`.env`** not writable → paste a key manually.
- Read **`storage/logs/laravel.log`** via File Manager (set **`APP_DEBUG=true`** briefly only to debug, then **`false`**).