# CoreERP — Deployment Checklist

> **Project:** CoreERP — TAN General Supply Limited  
> **Framework:** Laravel 13.8 (PHP 8.3+)  
> **Date prepared:** 2026-07-14

---

## 1. Server Requirements

| Requirement | Minimum |
|-------------|---------|
| PHP | **8.3** or higher (required by `composer.json`) |
| Database | MySQL 8.0+ or MariaDB 10.6+ |
| Composer | 2.x |
| Node.js | 18.x or higher |
| npm | 9.x or higher |
| Web server | Apache 2.4+ or Nginx 1.20+ |
| SSL certificate | Required for production (HTTPS) |

---

## 2. Required PHP Extensions

The following PHP extensions must be enabled on the production server:

- `php-mbstring`
- `php-xml`
- `php-bcmath`
- `php-curl`
- `php-zip`
- `php-gd` (for image processing)
- `php-pdo`
- `php-pdo_mysql`
- `php-tokenizer`
- `php-json`
- `php-openssl`
- `php-fileinfo`

Verify with:

```bash
php -m | grep -E "mbstring|xml|bcmath|curl|zip|gd|pdo|tokenizer|json|openssl|fileinfo"
```

---

## 3. Environment Setup

### 3.1 Copy the example environment file

```bash
cp .env.example .env
```

### 3.2 Edit `.env` — required values

```
APP_NAME="CoreERP"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_db_user
DB_PASSWORD=your_db_password

SESSION_DRIVER=database
CACHE_STORE=database
QUEUE_CONNECTION=database
```

See `docs/ENV_PRODUCTION_TEMPLATE.md` for a complete safe reference.

> **CRITICAL:** `APP_DEBUG=false` must be set in production. Leaving it `true` exposes stack traces and environment values to end users.

---

## 4. Laravel Setup Commands

Run these commands **in order** after uploading files to the server:

```bash
# 1. Install PHP dependencies (no dev packages)
composer install --no-dev --optimize-autoloader

# 2. Generate app key (first install only — do NOT run again on an existing deployment
#    as it will invalidate all sessions and encrypted data)
php artisan key:generate

# 3. Run all database migrations
php artisan migrate

# 4. Seed initial roles, permissions, currencies, and default admin user
php artisan db:seed --class=PhaseOneSeeder

# 5. Clear and reset Spatie permission cache
php artisan permission:cache-reset

# 6. Create the symbolic link from public/storage to storage/app/public
php artisan storage:link

# 7. Cache configuration for performance
php artisan config:cache

# 8. Cache routes for performance
php artisan route:cache

# 9. Cache compiled views for performance
php artisan view:cache
```

> **Note:** Do NOT run `php artisan key:generate` on subsequent deployments if the application is already running and has live sessions/encrypted data.

---

## 5. Frontend Assets (Vite Build)

This project uses Vite with Tailwind CSS, Alpine.js, and Font Awesome. Frontend assets must be compiled:

```bash
# Install Node dependencies
npm install

# Build production assets
npm run build
```

The compiled assets are written to `public/build/`. Verify this folder exists after building.

> AdminLTE assets are managed via Composer (`jeroennoten/laravel-adminlte`). They are published automatically; no separate build step is required for AdminLTE.

---

## 6. File Permissions

The web server user (typically `www-data` on Ubuntu/Debian, `apache` on CentOS) must have write access to:

```bash
# Make storage writable
chmod -R 775 storage/
chown -R www-data:www-data storage/

# Make bootstrap/cache writable
chmod -R 775 bootstrap/cache/
chown -R www-data:www-data bootstrap/cache/
```

> If using a shared hosting environment, `755` may be required instead of `775`.

---

## 7. Web Server Configuration

### Apache (`.htaccess`)

The project includes a `public/.htaccess` file. Ensure `mod_rewrite` is enabled:

```bash
a2enmod rewrite
```

Set `AllowOverride All` in the Apache virtual host block pointing to `public/`.

### Nginx

Point the Nginx root to the `public/` directory and configure the try_files directive:

```nginx
root /var/www/coreerp/public;
index index.php;

location / {
    try_files $uri $uri/ /index.php?$query_string;
}
```

---

## 8. Post-Deployment Checks

After deployment, verify the following manually:

- [ ] Login with admin credentials works (`admin@volex.local` — change password immediately after first login)
- [ ] Dashboard loads and charts display correctly
- [ ] No `APP_DEBUG=true` warnings visible in browser
- [ ] Sales flow: create quotation → proforma → sales order → dispatch → delivery note → tax invoice → receipt
- [ ] Purchase flow: purchase request → purchase order → GRN → supplier invoice → supplier payment
- [ ] Print documents (tax invoice, delivery note, gate pass) open correctly
- [ ] Storage link works: `ls -la public/storage` should be a symlink
- [ ] Company logo and images display in `public/company/`
- [ ] Backup test: take a manual backup and verify it is non-empty

---

## 9. Rollback Notes

> **Always take a full database backup before running migrations on production.**

If a deployment fails:

1. **Do NOT run `php artisan migrate:rollback` in production unless you have a tested rollback plan.**
2. Restore the database from the pre-deployment backup.
3. Re-deploy the previous codebase version.
4. Only run targeted, tested rollbacks when absolutely necessary and with stakeholder approval.

---

## 10. Maintenance Mode

Put the application into maintenance mode before running migrations:

```bash
php artisan down --message="System update in progress. Back shortly." --retry=60
# ... run migrations and commands ...
php artisan up
```

---

*Prepared as part of Phase 15A-15C — Backup & Deployment Preparation.*