# HƯỚNG DẪN DEPLOY LARAVEL + VUE.JS + INERTIA.JS VỚI SSR

## Tổng quan

Hướng dẫn này mô tả cách deploy dự án Laravel 12 + Vue.js 3 + Inertia.js với chế độ SSR (Server-Side Rendering) lên server production sử dụng Apache2 và PM2.

### Yêu cầu hệ thống

- **Server**: Ubuntu/Linux với Apache2 đã cài đặt
- **Node.js**: Version 18+ (khuyến nghị v22)
- **PHP**: Version 8.2+
- **PM2**: Process manager cho Node.js
- **SSL**: Đã cấu hình SSL certificate
- **Database**: MySQL/MariaDB hoặc SQLite

### Cấu trúc dự án

```
project/
├── app/                    # Laravel backend
├── resources/js/           # Vue.js frontend
├── public/                 # Public assets
├── bootstrap/ssr/          # SSR build files
├── config/                 # Laravel config
├── ecosystem.config.cjs    # PM2 configuration
└── vite.config.ts         # Vite configuration
```

---

## BƯỚC 1: CHUẨN BỊ SERVER

### 1.1. Kiểm tra môi trường hiện tại

```bash
# SSH vào server
ssh your_server

# Kiểm tra Apache
sudo systemctl status apache2

# Kiểm tra PHP
php -v

# Kiểm tra Node.js và npm hiện tại
node -v
npm -v
```

### 1.2. Upload code lên server

```bash
# Clone hoặc upload code vào thư mục
cd /var/www/html/your-project

# Cài đặt dependencies
composer install --no-dev --optimize-autoloader
npm install
```

---

## BƯỚC 2: CẤU HÌNH NODE.JS

### 2.1. Cài đặt Node.js phiên bản mới

```bash
# Di chuyển đến thư mục dự án
cd /var/www/html/your-project

# Tạo file .nvmrc để lock version Node.js
echo "22" > .nvmrc

# Load NVM và cài đặt Node.js v22
source ~/.nvm/nvm.sh
nvm install 22
nvm use 22

# Kiểm tra version
node -v    # Kết quả: v22.17.0
npm -v     # Kết quả: 10.9.2
```

### 2.2. Cài đặt/Cập nhật PM2

```bash
# Gỡ PM2 cũ nếu có
npm uninstall -g pm2

# Xóa cache PM2
rm -rf ~/.pm2

# Cài PM2 mới với Node.js v22
npm install -g pm2@latest

# Kiểm tra version
pm2 --version    # Kết quả: 6.0.8
```

---

## BƯỚC 3: CẤU HÌNH ENVIRONMENT

### 3.1. Cập nhật file .env cho production

```bash
# Sửa file .env
nano .env
```

Nội dung cần cập nhật:

```env
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

# Database configuration
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password

# Cache configuration
CACHE_STORE=database
SESSION_DRIVER=database
QUEUE_CONNECTION=database
```

### 3.2. Tạo key và clear cache

```bash
# Tạo application key
php artisan key:generate

# Clear cache
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear

# Optimize cho production
php artisan config:cache
php artisan route:cache
php artisan view:cache
```

---

## BƯỚC 4: BUILD ASSETS VỚI SSR

### 4.1. Kiểm tra cấu hình Vite

File `vite.config.ts` cần có cấu hình SSR:

```typescript
import vue from '@vitejs/plugin-vue';
import laravel from 'laravel-vite-plugin';
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
    plugins: [
        laravel({
            input: ['resources/js/app.ts'],
            ssr: 'resources/js/ssr.ts',
            refresh: true,
        }),
        tailwindcss(),
        vue({
            template: {
                transformAssetUrls: {
                    base: null,
                    includeAbsolute: false,
                },
            },
        }),
    ],
});
```

### 4.2. Build assets

```bash
# Đảm bảo sử dụng Node.js v22
source ~/.nvm/nvm.sh
nvm use 22

# Build assets với SSR support
npm run build:ssr
```

**Kết quả mong đợi:**
- Thư mục `public/build/` chứa client assets
- Thư mục `bootstrap/ssr/` chứa SSR files
- File `bootstrap/ssr/ssr.js` được tạo

### 4.3. Kiểm tra files đã build

```bash
# Kiểm tra SSR files
ls -la bootstrap/ssr/
# Kết quả: ssr.js, ssr-manifest.json, assets/

# Kiểm tra public assets
ls -la public/build/
# Kết quả: manifest.json, assets/
```

---

## BƯỚC 5: CẤU HÌNH PM2

### 5.1. Tạo file ecosystem.config.cjs

```bash
# Tạo file PM2 configuration
cat > ecosystem.config.cjs << 'EOF'
module.exports = {
    apps: [{
        name: 'your-project-ssr',
        script: './bootstrap/ssr/ssr.js',
        instances: 1,
        exec_mode: 'cluster',
        interpreter: 'node',
        interpreter_args: '--max-old-space-size=1024',
        env: {
            NODE_ENV: 'production',
            SERVER_PORT: 13714
        },
        error_file: './storage/logs/ssr-error.log',
        out_file: './storage/logs/ssr-out.log',
        log_file: './storage/logs/ssr-combined.log',
        time: true
    }]
}
EOF
```

### 5.2. Khởi động PM2

```bash
# Khởi động SSR process
pm2 start ecosystem.config.cjs

# Kiểm tra status
pm2 status

# Kiểm tra logs
pm2 logs your-project-ssr

# Lưu configuration
pm2 save

# Setup auto-start khi server reboot
pm2 startup
```

### 5.3. Kiểm tra SSR server

```bash
# Kiểm tra port đang lắng nghe
netstat -tlnp | grep 13714
# Kết quả: tcp6 0 0 :::13714 :::* LISTEN

# Test health endpoint
curl http://localhost:13714/health
# Kết quả: {"status":"OK","timestamp":1752518772749}
```

---

## BƯỚC 6: CẤU HÌNH APACHE

### 6.1. Tạo Virtual Host

```bash
# Tạo file virtual host
sudo nano /etc/apache2/sites-available/yourdomain.com-le-ssl.conf
```

Nội dung file:

```apache
<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerAdmin admin@yourdomain.com
    ServerName yourdomain.com
    DocumentRoot /var/www/html/your-project/public

    # Security Headers
    Header always set X-Frame-Options "SAMEORIGIN"
    Header always set X-XSS-Protection "1; mode=block"
    Header always set X-Content-Type-Options "nosniff"
    Header always set Referrer-Policy "strict-origin-when-cross-origin"
    
    # Basic Directory Config
    <Directory /var/www/html/your-project/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted

        # Laravel URL Rewriting
        RewriteEngine On
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule ^(.*)$ /index.php [QSA,L]
    </Directory>

    # Proxy for SSR
    ProxyPreserveHost On
    ProxyPass /ssr/ http://localhost:13714/
    ProxyPassReverse /ssr/ http://localhost:13714/

    # Enable required modules
    LoadModule rewrite_module modules/mod_rewrite.so
    LoadModule proxy_module modules/mod_proxy.so
    LoadModule proxy_http_module modules/mod_proxy_http.so

    # Logging
    ErrorLog ${APACHE_LOG_DIR}/your_project_error.log
    CustomLog ${APACHE_LOG_DIR}/your_project_access.log combined
    LogLevel warn

    # SSL Configuration
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/yourdomain.com/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/yourdomain.com/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf
</VirtualHost>
</IfModule>
```

### 6.2. Enable site và restart Apache

```bash
# Enable site
sudo a2ensite yourdomain.com-le-ssl.conf

# Enable required modules
sudo a2enmod rewrite
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod ssl
sudo a2enmod headers

# Test Apache configuration
sudo apache2ctl configtest

# Restart Apache
sudo systemctl restart apache2

# Kiểm tra status
sudo systemctl status apache2
```

---

## BƯỚC 7: CẤU HÌNH LARAVEL CHO SSR

### 7.1. Cấu hình Inertia.js

```bash
# Sửa file config/inertia.php
nano config/inertia.php
```

Thêm cấu hình SSR:

```php
<?php

return [
    // ... existing config

    /*
    |--------------------------------------------------------------------------
    | Server Side Rendering
    |--------------------------------------------------------------------------
    */
    'ssr' => [
        'enabled' => true,
        'url' => 'http://localhost:13714',
        'bundle' => public_path('build/ssr/ssr.js'),
    ],
];
```

### 7.2. Cập nhật permissions

```bash
# Set proper permissions
sudo chown -R www-data:www-data /var/www/html/your-project
sudo chmod -R 755 /var/www/html/your-project
sudo chmod -R 775 /var/www/html/your-project/storage
sudo chmod -R 775 /var/www/html/your-project/bootstrap/cache
```

---

## BƯỚC 8: KIỂM TRA VÀ TEST

### 8.1. Kiểm tra các dịch vụ

```bash
# Kiểm tra PM2
pm2 status
pm2 logs your-project-ssr

# Kiểm tra Apache
sudo systemctl status apache2
tail -f /var/log/apache2/your_project_error.log

# Kiểm tra SSR endpoint
curl http://localhost:13714/health

# Kiểm tra website
curl -I https://yourdomain.com
```

### 8.2. Test SSR hoạt động

```bash
# Kiểm tra source code có render SSR
curl -s https://yourdomain.com | grep -i "<!DOCTYPE html>"

# Kiểm tra performance
curl -w "@curl-format.txt" -o /dev/null -s https://yourdomain.com
```

### 8.3. Monitoring và logs

```bash
# Monitor PM2 processes
pm2 monit

# Xem logs real-time
pm2 logs --lines 50

# Xem Apache logs
tail -f /var/log/apache2/your_project_access.log
tail -f /var/log/apache2/your_project_error.log
```

---

## TROUBLESHOOTING

### Vấn đề thường gặp

#### 1. PM2 báo lỗi `availableParallelism`

**Nguyên nhân:** Node.js version quá cũ  
**Giải pháp:** Cài đặt Node.js v18+ và cài lại PM2

```bash
nvm install 22
nvm use 22
npm uninstall -g pm2
npm install -g pm2@latest
pm2 kill
pm2 start ecosystem.config.cjs
```

#### 2. Apache không proxy được đến SSR

**Nguyên nhân:** Module proxy chưa enable  
**Giải pháp:**

```bash
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo systemctl restart apache2
```

#### 3. File permissions

**Nguyên nhân:** Laravel không có quyền write  
**Giải pháp:**

```bash
sudo chown -R www-data:www-data /var/www/html/your-project
sudo chmod -R 775 storage bootstrap/cache
```

#### 4. SSR build failed

**Nguyên nhân:** Dependencies thiếu hoặc cấu hình sai  
**Giải pháp:**

```bash
# Kiểm tra file vite.config.ts
# Kiểm tra file resources/js/ssr.ts
npm install
npm run build:ssr
```

### Các lệnh hữu ích

```bash
# Restart tất cả services
pm2 restart all
sudo systemctl restart apache2

# Clear cache Laravel
php artisan cache:clear
php artisan config:clear

# Rebuild assets
npm run build:ssr

# Check ports
netstat -tlnp | grep -E '(80|443|13714)'

# Monitor resources
htop
pm2 monit
```

---

## KẾT LUẬN

Sau khi hoàn thành tất cả các bước trên, bạn sẽ có:

1. ✅ Laravel application chạy với Apache
2. ✅ Vue.js frontend với SSR support
3. ✅ PM2 quản lý SSR process
4. ✅ SSL/HTTPS đã cấu hình
5. ✅ Auto-restart khi server reboot
6. ✅ Logging và monitoring

### Performance Benefits

- **SEO tốt hơn**: Content được render sẵn trên server
- **First Paint nhanh hơn**: User thấy content ngay lập tức
- **Social Media**: Meta tags được render đúng cho sharing

### Maintenance

```bash
# Daily checks
pm2 status
sudo systemctl status apache2

# Weekly updates
npm update
composer update
```

**Lưu ý quan trọng:** Luôn backup database và code trước khi deploy hoặc update!