# CoreERP — cPanel Export Manifest
**Phase 32B — 2026-08-25**
**Export package:** `storage/app/reports/coreerp-cpanel-export.zip`

---

## 1. Files and Folders to INCLUDE

| Path | Notes |
|------|-------|
| `app/` | All controllers, models, services, middleware |
| `bootstrap/` | App bootstrap — includes `bootstrap/cache/` (cleared before package) |
| `config/` | All Laravel config files |
| `database/migrations/` | All 103 migrations |
| `database/seeders/` | PhaseOneSeeder (run on fresh DB), DatabaseSeeder |
| `public/` | Web root — index.php, .htaccess, robots.txt, favicon |
| `public/build/` | Vite compiled CSS + JS (fresh build 2026-08-25) |
| `public/vendor/adminlte/` | Bootstrap 4 CSS base used by Inspinia layouts |
| `public/vendor/inspinia/` | Inspinia theme assets (CSS, JS, fonts) |
| `public/vendor/bootstrap/` | Bootstrap JS/CSS |
| `public/vendor/fontawesome-free/` | FA5 icons |
| `public/vendor/jquery/` | jQuery |
| `public/vendor/overlayScrollbars/` | Scrollbar plugin |
| `public/vendor/popper/` | Popper.js |
| `public/company/` | Company logos and print images |
| `resources/` | All Blade views, CSS, JS sources |
| `routes/` | web.php and any other route files |
| `storage/app/` | App-level storage (excluding logs/framework cache) |
| `composer.json` | Composer dependency definition |
| `composer.lock` | Locked dependency versions |
| `package.json` | NPM dependency definition |
| `package-lock.json` | Fresh lock file (regenerated 2026-08-25) |
| `.env.cpanel.example` | Production env template (no real secrets) |
| `.gitignore` | For reference (not needed on server but harmless) |
| `docs/` | Deployment guides and training documentation |
| `artisan` | Laravel CLI |

---

## 2. Files and Folders to EXCLUDE

| Path | Reason |
|------|--------|
| `.env` | Contains local secrets — NEVER upload |
| `.env.backup`, `.env.production` | Local variants — never upload |
| `.git/` | Version control history — not needed on server |
| `node_modules/` | Rebuilt on server or not needed if assets pre-built |
| `storage/logs/*.log` | Local dev logs — start fresh on server |
| `storage/framework/cache/data/` | Regenerated by Laravel on first request |
| `storage/framework/sessions/` | Regenerated by Laravel |
| `storage/framework/views/` | Blade compiled views — regenerated by `view:cache` |
| `storage/app/reports/*.zip` | Local export packages — not part of application |
| `tests/` | PHPUnit tests — not needed on production |
| `storage/pail/` | Laravel Pail dev tool logs |
| `public/hot` | Vite dev server indicator — not needed on production |
| `public/storage` | Symlink — recreate on server with `storage:link` |
| `.DS_Store`, `Thumbs.db` | OS metadata files |
| `*.local`, `Homestead.*` | Dev environment files |

---

## 3. vendor/ Directory Note

Two options depending on cPanel SSH access:

**Option A — Run composer on server (preferred if SSH available):**
- Exclude `vendor/` from ZIP (reduces package size by ~80 MB).
- After uploading, run: `composer install --no-dev --optimize-autoloader`

**Option B — Include vendor/ in ZIP (no SSH needed):**
- Include `vendor/` in ZIP.
- Do NOT run `composer install` on server (use uploaded vendor as-is).
- Package will be ~80 MB larger.
- Package created with **vendor/ included** for maximum cPanel compatibility.

---

## 4. Deployment Steps (Run on cPanel After Upload)

Run these in order via cPanel Terminal or SSH:

```bash
# 1. Create production .env from template
cp .env.cpanel.example .env
# Edit .env with production values (DB, APP_URL, APP_KEY, MAIL, etc.)
nano .env

# 2. Generate APP_KEY (only if fresh install — preserve key if migrating)
php artisan key:generate

# 3. Install composer dependencies (if vendor/ excluded from package)
composer install --no-dev --optimize-autoloader

# 4. Run migrations
php artisan migrate --force

# 5. Seed permissions/roles/admin (fresh DB only — NOT on existing data)
php artisan db:seed --class=PhaseOneSeeder --force

# 6. Create public storage symlink
php artisan storage:link
# If symlink fails (shared hosting):
# ln -s /home/username/coreerp/storage/app/public /home/username/public_html/storage

# 7. Reset Spatie permission cache
php artisan permission:cache-reset

# 8. Production optimizations
php artisan config:cache
php artisan view:cache
# php artisan route:cache  # Only if no closure routes in web.php

# 9. Set storage permissions
find storage -type d -exec chmod 755 {} \;
find storage -type f -exec chmod 644 {} \;
find bootstrap/cache -type d -exec chmod 755 {} \;
chmod 644 .env

# 10. Setup cron for scheduler (in cPanel Cron Jobs)
# * * * * * php /home/username/coreerp/artisan schedule:run >> /dev/null 2>&1
```

---

## 5. Post-Upload Checks

- [ ] `https://your-domain.com/login` loads without error
- [ ] Login with `admin@volex.local` / `admin12345`
- [ ] **Change password immediately after first login**
- [ ] Dashboard loads
- [ ] Sidebar navigation works
- [ ] Key module pages render (customers, items, sales orders, etc.)
- [ ] Print documents render
- [ ] Mail settings test (only after SMTP configured)

---

## 6. cPanel Document Root Configuration

**Preferred setup (project outside public_html):**
```
/home/username/
├── coreerp/          ← full project here
│   ├── app/
│   ├── public/       ← set this as document root
│   └── ...
└── public_html/      ← should NOT be the document root for CoreERP
```

In cPanel → Domains → your domain → Document Root → set to: `/home/username/coreerp/public`

**Alternative (if document root cannot be changed):**
- Copy contents of `public/` into `public_html/`
- Update `public_html/index.php` to set `__DIR__.'/../coreerp'` paths
- This is not recommended — harder to maintain

---

## 7. Package Verification Checklist

After creating the ZIP, verify:

- [ ] `.env` is NOT in the ZIP
- [ ] `node_modules/` is NOT in the ZIP
- [ ] `.git/` is NOT in the ZIP
- [ ] `public/build/` IS in the ZIP
- [ ] `public/vendor/inspinia/` IS in the ZIP
- [ ] `public/vendor/adminlte/` IS in the ZIP
- [ ] `composer.json` IS in the ZIP
- [ ] `composer.lock` IS in the ZIP
- [ ] `.env.cpanel.example` IS in the ZIP
- [ ] `artisan` IS in the ZIP

---

## 8. No-CLI Web Interface Package — Phase 32B-UI (2026-08-25)

**Package:** `storage/app/reports/coreerp-cpanel-webui-export.zip`

This package differs from the Phase 32B package only in the addition of the browser-based
setup helper `public/coreerp-cpanel-setup.php`. All other includes/excludes are identical.

### Additional Include

| Path | Notes |
|------|-------|
| `public/coreerp-cpanel-setup.php` | Token-protected 8-step browser setup helper |

### How to Use the Setup Helper

1. Extract `coreerp-cpanel-webui-export.zip` to the project root on the server
2. Create `.env` from `.env.cpanel.example`:
   - Set `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`
   - Set `APP_URL=https://office.tangeneralsupply.co.tz`
   - Set `CPANEL_SETUP_TOKEN` to a long random string (32+ characters)
   - Leave `APP_KEY=` blank (setup helper generates it)
3. Visit: `https://office.tangeneralsupply.co.tz/coreerp-cpanel-setup.php?token=YOUR_TOKEN`
4. Run Steps 1–8 in order
5. **Delete `public/coreerp-cpanel-setup.php` via cPanel File Manager immediately after Step 8**
6. Login at `/login` with `admin@volex.local` / `admin12345` — change password immediately

### No-CLI Package Verification Checklist

- [ ] `.env` is NOT in the ZIP
- [ ] `node_modules/` is NOT in the ZIP
- [ ] `.git/` is NOT in the ZIP
- [ ] `public/build/` IS in the ZIP
- [ ] `public/vendor/inspinia/` IS in the ZIP
- [ ] `public/vendor/adminlte/` IS in the ZIP
- [ ] `public/coreerp-cpanel-setup.php` IS in the ZIP
- [ ] `composer.json` IS in the ZIP
- [ ] `composer.lock` IS in the ZIP
- [ ] `.env.cpanel.example` IS in the ZIP (with CPANEL_SETUP_TOKEN key)
- [ ] `artisan` IS in the ZIP

### Security Reminder

- `CPANEL_SETUP_TOKEN` must be a long random string set in `.env` before first access
- The setup helper uses `hash_equals()` for constant-time token comparison
- Secrets are redacted from all Artisan output displayed in the browser
- Delete the setup file and clear `CPANEL_SETUP_TOKEN` from `.env` after deployment

## Phase 32B-UI Easy No-CLI Package Update

This package has been adjusted for cPanel accounts without Terminal/SSH access.

### New helper

- `public/coreerp-cpanel-setup.php` is a temporary browser setup helper.
- It is protected by `CPANEL_SETUP_TOKEN` from `.env`.
- It can generate `APP_KEY` without CLI by writing directly to `.env` when APP_KEY is blank.
- It can run migrations, PhaseOneSeeder, storage link, permission cache reset, and cache commands through Laravel Artisan after APP_KEY and DB are configured.
- It must be deleted immediately after setup.

### Easier APP_KEY handling

- `.env.cpanel.example` now leaves `APP_KEY=` blank.
- If the app is opened before APP_KEY is set, `public/index.php` shows a friendly setup-required page instead of a generic 500.
- Use `/coreerp-cpanel-setup.php?token=YOUR_TOKEN` to generate APP_KEY.

### No-CLI steps

1. Upload and extract the ZIP through cPanel File Manager.
2. Copy `.env.cpanel.example` to `.env`.
3. Fill APP_URL, DB credentials, and CPANEL_SETUP_TOKEN.
4. Open `/coreerp-cpanel-setup.php?token=YOUR_TOKEN`.
5. Run buttons in order.
6. Delete `public/coreerp-cpanel-setup.php`.
7. Login and change the default admin password.