# Mettle — Deployment Guide

## Prerequisites

- cPanel shared hosting with PHP 8.2+ (select in cPanel → PHP Version)
- MySQL or MariaDB database created in cPanel
- SMTP mail credentials
- FTP/SFTP access or cPanel File Manager

---

## Layout A — Preferred (domain root points to `public/`)

Use this when your host lets you set the document root to a subdirectory.

```
/home/USER/
├── Mettle/          ← app lives here (not web-accessible)
│   ├── app/
│   ├── vendor/
│   ├── storage/
│   ├── .env         ← upload separately, never in the zip
│   ├── bootstrap.php
│   └── public/      ← point domain document root here
│       ├── index.php
│       └── .htaccess
```

In cPanel → Domains → your domain → Document Root: set to `public_html/../Mettle/public`
(exact path depends on your host; some use `/home/USER/Mettle/public`).

---

## Layout B — Fallback (document root fixed to `public_html/`)

Use this when the host fixes the document root to `public_html/`.

```
/home/USER/
├── Mettle/          ← app lives here
│   ├── app/
│   ├── vendor/
│   ├── storage/
│   ├── .env
│   └── bootstrap.php
└── public_html/     ← web root (fixed by host)
    ├── index.php    ← modified version (see below)
    ├── .htaccess
    └── assets/      ← copy of Mettle/public/assets/
```

Modify `public_html/index.php` to:
```php
<?php
$app = require dirname(__DIR__) . '/Mettle/bootstrap.php';
$app->run();
```

Copy `public/assets/` to `public_html/assets/` as part of your deployment script.

---

## Deployment Steps

### 1. Build locally

```bash
# Install production dependencies
composer install --no-dev --optimize-autoloader

# Compile Tailwind CSS (download tailwindcss binary first)
./tailwindcss -i resources/css/app.css -o public/assets/css/app.css --minify

# Package for upload
composer run package
# Creates: dist/Mettle-<version>.zip
```

### 2. Upload

- Upload `dist/Mettle-<version>.zip` via cPanel File Manager or SFTP
- Extract into `/home/USER/` (creates `/home/USER/Mettle/`)
- Upload your `.env` file to `/home/USER/Mettle/.env` (or one level above for Layout A)
- Set file permissions: `chmod 600 .env`

### 3. Run migrations

Visit: `https://yourdomain.com/admin/maintenance/migrate?token=YOUR_MIGRATE_TOKEN`

Or log in as admin and use the Admin Dashboard → Run Migrations button.

### 4. Set up cron

In cPanel → Cron Jobs, add:
```
*/5 * * * * /usr/local/bin/php /home/USER/Mettle/bin/cron.php
```

Replace `/usr/local/bin/php` with the path shown in cPanel → PHP Version → path.

### 5. Verify

- Visit your domain — you should see the Mettle home page
- Check `storage/logs/app.log` for any errors
- Check `storage/logs/cron-error.log` after 5 minutes

---

## Storage Directory Permissions

```bash
chmod 750 storage/
chmod 750 storage/logs/
chmod 750 storage/cache/
chmod 750 storage/uploads/
chmod 750 storage/backups/
```

---

## Maintenance Mode

To enable: create the file `storage/maintenance.flag` (empty file is fine).
To disable: delete `storage/maintenance.flag`.

Admins bypass maintenance mode automatically.

---

## Updating

1. Build and package locally as above
2. Upload and extract the new zip (overwrites app files, leaves `.env` and `storage/` intact)
3. Run migrations via the admin endpoint
4. Clear Twig cache: delete `storage/cache/twig/`