# cPanel Deployment Guide

This application is designed to run efficiently on shared cPanel hosting without requiring advanced services like Redis, resident queue workers, or Node.js.

## Prerequisites
- cPanel access.
- PHP 8.3 or 8.4 enabled via MultiPHP Manager.
- PostgreSQL 12+ (or MySQL 8.0+).

## Directory Layout (Preferred)

We recommend creating a subdomain (e.g., `go.example.com`) and mapping its Document Root directly to the `public` folder of the application.

```text
/home/CPANEL_USER/apps/onisokien-links/        # Private application root
/home/CPANEL_USER/apps/onisokien-links/public/ # Public document root (go.example.com)
```

## Initial Setup (Upload Workflow)

1. Run Composer locally (or in a CI pipeline) to prepare the vendor folder:
   ```bash
   composer install --no-dev --prefer-dist --optimize-autoloader
   ```
2. Zip the entire directory, excluding `.env`, `.git`, `tests`, and local logs.
3. Upload the Zip file to `/home/CPANEL_USER/apps/onisokien-links/` and extract it via cPanel File Manager.
4. Set folder permissions: `storage` and `bootstrap/cache` must be writable by the web server (typically `755`). Do not use `777`.

## Database Setup

1. In cPanel **PostgreSQL Databases**, create a new database and user. Grant all privileges to the user.
2. In the application folder, copy `.env.example` to `.env`.
3. Update `.env` with your production details (see `.env.example` for the required keys).
   - Important: Set `APP_ENV=production`, `APP_DEBUG=false`, and force `SESSION_SECURE_COOKIE=true`.
   - Set a unique `ANALYTICS_HASH_KEY`.
4. Generate the app key via SSH:
   ```bash
   php artisan key:generate
   ```
5. Run the database migrations via SSH:
   ```bash
   php artisan migrate --force
   ```

## Creating the First Admin

Run the idempotent admin creation command via SSH:
```bash
php artisan app:admin-user --name="Administrator" --email="admin@yourdomain.com"
```
The command will prompt you securely for a password.

## Optimizing

Run these commands to cache routes, config, and views:
```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

## Setting up Cron

Add the following to cPanel **Cron Jobs** to run every minute (`* * * * *`). Replace paths appropriately:
```cron
* * * * * /usr/local/bin/php /home/CPANEL_USER/apps/onisokien-links/artisan schedule:run >> /dev/null 2>&1
```

## Updates and Rollbacks

For future updates, upload the new files over the existing ones, run `php artisan migrate --force` if schema changes exist, and clear caches `php artisan optimize`. Always backup your database before migrating.