# Deployment Guide: Laravel App on Ubuntu 22.04 LTS

This guide details the steps to deploy this Laravel application to an Ubuntu 22.04 server that already hosts another Laravel application.

## Prerequisites

Ensure the server has the required software versions installed. This project requires:
- **PHP**: 8.3 or higher
- **Node.js**: 22.x
- **Composer**
- **Database Engine** (MySQL/MariaDB or PostgreSQL)

## 1. Project Setup

### 1.1. Upgrade to PHP 8.3 (If needed)
If your server is running an older version of PHP, upgrade to PHP 8.3:
```bash
sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

# Install PHP 8.3 and required extensions
sudo apt install -y php8.3 libapache2-mod-php8.3 php8.3-cli php8.3-mysql php8.3-xml php8.3-mbstring php8.3-curl php8.3-zip php8.3-bcmath php8.3-intl php8.3-gd

# Disable the old version module (replace '?' with your old PHP version, e.g., '8.1' or '8.2')
sudo a2dismod php?

# Enable the new version module
sudo a2enmod php8.3

# Restart Apache to apply the changes
sudo systemctl restart apache2

# Set the Terminal (CLI) Version
sudo update-alternatives --set php /usr/bin/php8.3
```

### 1.2. Directory Structure
Navigate to your web root (typically `/var/www/`). Create a directory for the new app.
```bash
cd /var/www/
sudo mkdir new-app-name
sudo chown -R $USER:$USER new-app-name
```
*Replace `new-app-name` with your desired folder name.*

### 1.3. Clone Repository
Clone your project into this directory.
```bash
git clone https://github.com/your-username/your-repo.git new-app-name
cd new-app-name
```

### 1.4. Install PHP Dependencies
```bash
composer install --optimize-autoloader --no-dev
```

### 1.5. Environment Configuration
Copy the example environment file and configure it.
```bash
cp .env.example .env
nano .env
```
**Critical Settings to Update:**
- `APP_URL`: Set to the full URL (e.g., `https://app2.yourdomain.com`).
- `DB_*`: Database credentials (create a new database for this app).
- `QUEUE_CONNECTION`: Set to `database` or `redis`.
- `filesystem`: Ensure paths are correct.

Generate the application key:
```bash
php artisan key:generate
```

### 1.6. Database Migration
```bash
php artisan migrate --force
```

### 1.7. Storage Link
Create the symbolic link to make files in `storage/app/public` accessible from the web.
```bash
php artisan storage:link
```

### 1.8. Frontend Assets (If applicable)
If you compile assets on production:
```bash
npm ci
npm run build
```

### 1.9. Permissions
Set permissions for the web user (`www-data`).
```bash
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
```

## 2. Web Server Configuration (Apache)

Since you already have an app running, you simply need a **new Virtual Host** file for this application.

### 2.1. Enable Mod Rewrite
Ensure the rewrite module is enabled:
```bash
sudo a2enmod rewrite
```

### 2.2. Create Virtual Host
Create a new config file:
```bash
sudo nano /etc/apache2/sites-available/new-app-name.conf
```

Paste the following configuration (adjust `ServerName`, `DocumentRoot`, and paths):

```apache
<VirtualHost *:80>
    ServerName app2.yourdomain.com
    DocumentRoot /var/www/new-app-name/public

    <Directory /var/www/new-app-name/public>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/new-app-error.log
    CustomLog ${APACHE_LOG_DIR}/new-app-access.log combined
</VirtualHost>
```

### 2.3. Enable Site and Reload Apache
```bash
sudo a2ensite new-app-name.conf
sudo systemctl reload apache2
```

### 2.4. Verify HTTPS (Certbot)
If you need HTTPS (recommended), run:
```bash
sudo certbot --apache -d app2.yourdomain.com
```

## 3. PDF Generation Dependencies

Since we are using `spatie/laravel-pdf` (Browsershot/Puppeteer), you must install the required system libraries for Chromium, and ensure you are on Node.js 22.x.

### 3.1. Upgrade to Node.js 22.x (If needed)
If you need to install or upgrade to Node.js 22.x:
```bash
# Add Node.js 22.x repository
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# Install Node.js
sudo apt install -y nodejs
```

### 3.2. Install Chromium Dependencies
```bash
sudo apt-get update
sudo apt-get install -y ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 lsb-release wget xdg-utils
```

Verify Puppeteer can install and configure the cache for the web server user:
```bash
# Create the puppeteer cache directory for the web server user
sudo mkdir -p /var/www/.cache/puppeteer
sudo chown -R www-data:www-data /var/www/.cache

# Install chrome specifically for the www-data user
sudo -u www-data npx puppeteer browsers install chrome-headless-shell

# Inside your project folder, verify it works
node vendor/spatie/browsershot/bin/browser.js
```
*If this fails, you might need to ensure `npm ci` was run successfully or install puppeteer locally `npm install puppeteer`.*

## 4. Automation (Cron & Queues)

### 4.1. Scheduler (For Daily Reports)
Add the cron entry for the scheduler. This is **critical** for `trips:process` and `speed-limits:process`.

```bash
crontab -e
```
Add this line:
```cron
* * * * * cd /var/www/new-app-name && php artisan schedule:run >> /dev/null 2>&1
```

### 4.2. Queue Worker (Supervisor)
If you use queues, configure Supervisor.

First, install Supervisor:
```bash
sudo apt update
sudo apt install -y supervisor
```

Then configure it:
```bash
sudo nano /etc/supervisor/conf.d/new-app-name-worker.conf
```
Content:
```ini
[program:new-app-name-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/new-app-name/artisan queue:work database --sleep=3 --tries=3
autostart=true
autorestart=true
user=www-data
numprocs=2
redirect_stderr=true
stdout_logfile=/var/www/new-app-name/storage/logs/worker.log
stopwaitsecs=3600
```
Update Supervisor:
```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start new-app-name-worker:*
```

## 5. Summary Checklist
- [ ] Code cloned to separate directory.
- [ ] Dependencies installed (`composer`, `npm`).
- [ ] `.env` configured with unique DB/URL.
- [ ] Nginx server block created for new domain.
- [ ] System libraries installed for PDF generation.
- [ ] `schedule:run` added to cron.
- [ ] Permissions verified.