# Deploying Daily Epaper to cPanel

This is the checklist that prevents the usual "images don't load / 500 error /
blank page / 403 license" problems on shared cPanel hosting.

---

## 1. Upload

1. Zip the whole project **except** `node_modules` (not needed — all CSS/JS is
   loaded from CDN). Keep `vendor/` in the zip.
2. In cPanel **File Manager**, upload and extract to a folder **above**
   `public_html`, e.g. `/home/USER/epaper`.
3. Delete the local `public/storage` entry if it came across as a broken link
   (File Manager shows it as a 0-byte file). You will recreate it in step 4.

## 2. Point the domain at `/public`

Pick **one**:

- **Preferred:** cPanel → *Domains* → set the domain's *Document Root* to
  `/home/USER/epaper/public`.
- **Alternative:** move everything inside `epaper/public/` into `public_html/`,
  move the other folders (`app`, `vendor`, …) to `/home/USER/epaper`, then edit
  `public_html/index.php` lines 19 & 34 & 47 to point at
  `/home/USER/epaper/...`.

Never expose the project root as the document root — that leaks `.env`.

Then fix the rewrite base in `public/.htaccess` (or `public_html/.htaccess`):

- domain root (`https://example.com`)        → `RewriteBase /`
- sub-folder (`https://example.com/epaper`)   → `RewriteBase /epaper/`

## 3. Environment file

1. Copy `.env.production` → `.env` on the server.
2. Edit: `APP_URL=https://your-real-domain.com` (no trailing slash, no
   `/public`), real `DB_*` values, `APP_DEBUG=false`.
3. Keep the existing `APP_KEY` (already filled in). If it is ever blank, run
   `php artisan key:generate`.
4. Set `FORCE_HTTPS=true` **after** the SSL certificate is active (AutoSSL).

## 4. Database & storage link (cPanel → Terminal, or SSH)

```bash
cd ~/epaper
php artisan migrate --force
php artisan storage:link        # creates public/storage -> ../storage/app/public
php artisan optimize:clear
```

- No Terminal access? Create the symlink with a one-off PHP file in
  `public/`: `<?php symlink('/home/USER/epaper/storage/app/public', __DIR__.'/storage');`
  hit it once in the browser, then delete it.
- If the host blocks symlinks entirely, the site still shows images: the app
  has a built-in `/storage/{path}` fallback route that streams them through PHP.

## 5. Permissions

```bash
find ~/epaper/storage -type d -exec chmod 775 {} \;
find ~/epaper/bootstrap/cache -type d -exec chmod 775 {} \;
```

## 6. PHP version & extensions

- cPanel → **MultiPHP Manager**: set the domain to **PHP 8.0 or 8.1**.
- cPanel → **MultiPHP INI Editor** / *Select PHP Version → Extensions*: enable
  `gd` (or `imagick`), `fileinfo`, `mbstring`, `openssl`, `pdo_mysql`, `curl`,
  `zip`. `gd`/`imagick` is required for thumbnail generation (Intervention Image).

## 7. Upload size (large newspaper page images)

`public/.user.ini` is bundled (32 MB). If uploads still fail, set in
**MultiPHP INI Editor**: `upload_max_filesize=32M`, `post_max_size=40M`,
`max_execution_time=300`.

## 8. Final smoke test

- `https://domain.com/` loads with styling.
- `https://domain.com/admin` → log in (`admin@epaper.com` / `password`) →
  **change the password immediately** (Admin → Profile & Password).
- Upload a newspaper edition, open the reader, confirm page images + thumbnails
  show. If images 404: re-check step 4 (symlink) and `APP_URL` in step 3.

---

## What was changed in the code for hosting compatibility

| File | Change |
|---|---|
| `public/.htaccess` | `RewriteBase /epaper/` kept for local XAMPP (alias) — **change to `RewriteBase /` at a domain root on cPanel**; added `+FollowSymLinks`; commented HTTPS-redirect block; module-PHP upload limits |
| `public/.user.ini` | new — FPM/CGI upload limits |
| `app/Http/Middleware/TrustProxies.php` | trust host proxy headers so HTTPS is detected (fixes mixed-content images) |
| `app/Providers/AppServiceProvider.php` | `FORCE_HTTPS` env toggle |
| `routes/web.php` | `/storage/{path}` fallback so images load even without a symlink |
| `.env.production` | new — ready-to-edit live config template |