Deploy dự án Laravel lên cPanel bằng GitHub Actions sữ dụng SSH

byKhông Nên Tin •
0

Nếu bạn có SSH access vào cPanel, việc deploy qua GitHub Actions sẽ trở nên mạnh mẽ và đáng tin cậy hơn rất nhiều so với FTP. Bạn có thể chạy các lệnh Artisan trực tiếp trên server, bao gồm cả migrations và tối ưu hóa.


Dưới đây là hướng dẫn cập nhật để deploy Laravel lên cPanel bằng GitHub Actions, sử dụng SSH thay vì FTP:

I. Chuẩn bị trên cPanel

  1. Tạo Tài khoản SSH Access:

    • Đăng nhập vào cPanel của bạn.
    • Tìm mục "Security" (Bảo mật) và chọn "SSH Access".
    • Nhấp vào "Manage SSH Keys" (Quản lý SSH Keys).
    • Tạo một SSH Key mới (hoặc import nếu bạn đã có).
      • Chọn "Generate a New Key".
      • Đặt mật khẩu (passphrase) cho key (ghi nhớ kỹ mật khẩu này).
      • Sau khi tạo, quay lại trang "Manage SSH Keys".
      • Tìm key bạn vừa tạo và nhấp vào "Manage" (Quản lý) hoặc "Authorize" (Ủy quyền).
      • Kích hoạt key bằng cách nhấp vào "Authorize".
      • Tiếp theo, nhấp vào "View/Download" cho key vừa tạo. Copy toàn bộ nội dung của Private Key (bắt đầu bằng -----BEGIN OPENSSH PRIVATE KEY----- và kết thúc bằng -----END OPENSSH PRIVATE KEY-----).

  2. Lấy SSH Username và Hostname:

    • Username SSH: Thường giống với cPanel username của bạn. Bạn có thể thấy nó ở góc trên bên phải của cPanel hoặc trong thông tin tài khoản hosting.
    • Hostname SSH: Thường là tên miền chính của bạn (ví dụ: yourdomain.com hoặc sftp.yourdomain.com).
    • Ghi lại SSH Hostname, SSH Username, Private SSH Key và Passphrase của Private Key (nếu có).

  3. Cấu hình PHP trên cPanel:

    • Trong cPanel, tìm mục "Software" (Phần mềm) và chọn "Select PHP Version" (Chọn phiên bản PHP).
    • Chọn phiên bản PHP tương thích với Laravel của bạn (Laravel 10+ yêu cầu PHP 8.1+).
    • Đảm bảo các extension cần thiết cho Laravel được bật (ví dụ: pdo_mysql, mbstring, openssl, fileinfo, json, bcmath, curl).

  4. Cấu hình Document Root cho Laravel (Quan trọng):

    • Trong cPanel, tìm mục "Domains" (Tên miền) và chọn "Domains" hoặc "Subdomains".
    • Tìm tên miền/subdomain của dự án bạn.
    • Chỉnh sửa Document Root của nó từ /public_html/your-project thành /public_html/your-project/public.
    • Lưu thay đổi.

II. Chuẩn bị trên GitHub

  1. Thêm Secrets vào Repository: Để giữ an toàn cho thông tin SSH của bạn, chúng ta sẽ sử dụng GitHub Secrets.
    • Mở repository GitHub của dự án Laravel của bạn.
    • Đi tới "Settings" (Cài đặt) > "Secrets and variables" > "Actions".
    • Nhấp vào "New repository secret".
    • Thêm các secret sau:
      • SSH_HOST: Giá trị là địa chỉ máy chủ SSH của bạn (ví dụ: yourdomain.com).
      • SSH_USERNAME: Giá trị là tên đăng nhập SSH của bạn.
      • SSH_PRIVATE_KEY: Dán toàn bộ nội dung của Private SSH Key mà bạn đã copy từ cPanel (bao gồm cả -----BEGIN OPENSSH PRIVATE KEY----- và -----END OPENSSH PRIVATE KEY-----).
      • SSH_PASSPHRASE: (Chỉ thêm nếu Private Key của bạn có mật khẩu bảo vệ). Giá trị là mật khẩu bạn đã đặt cho Private Key.
      • SSH_TARGET_DIR: Giá trị là đường dẫn tuyệt đối đến thư mục gốc của dự án trên cPanel (ví dụ: /home/cpaneluser/public_html/my-laravel-app hoặc /home/cpaneluser/my-laravel-app). Thay cpaneluser bằng username cPanel của bạn.

III. Tạo GitHub Actions Workflow

  1. Tạo file Workflow:

    • Trong repository GitHub của bạn, tạo một thư mục mới .github/workflows/ (nếu chưa có).
    • Tạo một file .yml mới trong thư mục này, ví dụ: deploy_ssh.yml.

  2. Nội dung file deploy_ssh.yml: Sao chép và dán nội dung sau vào file deploy_ssh.yml, sau đó điều chỉnh cho phù hợp.

    YAML
    name: Deploy Laravel to cPanel via SSH

on:
  push:
    branches:
      - main # Hoặc tên branch bạn muốn deploy (ví dụ: production)

jobs:
  deploy:
    name: Deploy via SSH
    runs-on: ubuntu-latest
    environment: production # Bạn có thể dùng GitHub Environments để quản lý biến môi trường

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup PHP and Composer
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2' # Đảm bảo khớp với phiên bản PHP trên cPanel
          extensions: pdo_mysql, mbstring, tokenizer, xml, ctype, json, bcmath, fileinfo, curl
          ini-values: post_max_size=256M, upload_max_filesize=256M
          tools: composer:v2

      - name: Install Composer dependencies locally
        # Cài đặt dependencies trên runner của GitHub Actions
        run: composer install --no-dev --prefer-dist --optimize-autoloader

      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.9.0
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
          passphrase: ${{ secrets.SSH_PASSPHRASE }} # Chỉ thêm dòng này nếu key của bạn có passphrase

      - name: Clear known_hosts (Optional, for fresh connections)
        # Giúp tránh lỗi host key verification failed nếu server đổi IP
        run: ssh-keyscan -H ${{ secrets.SSH_HOST }} >> ~/.ssh/known_hosts

      - name: Rsync project files to cPanel
        # Rsync là công cụ đồng bộ hóa file hiệu quả qua SSH
        # -avz: Archive mode, verbose, compress
        # --delete: Xóa các file trên server không còn tồn tại ở local (CẨN TRỌNG!)
        # --exclude: Loại trừ các thư mục không cần thiết
        run: |
          ssh ${{ secrets.SSH_USERNAME }}@${{ secrets.SSH_HOST }} "mkdir -p ${{ secrets.SSH_TARGET_DIR }}" # Đảm bảo thư mục đích tồn tại
          rsync -avz --delete \
            --exclude '.git/' \
            --exclude '.github/' \
            --exclude 'node_modules/' \
            --exclude '.env' \
            --exclude 'storage/' \
            --exclude 'vendor/' \
            ./ ${{ secrets.SSH_USERNAME }}@${{ secrets.SSH_HOST }}:${{ secrets.SSH_TARGET_DIR }}

      - name: Run Composer Install on server (for vendor folder)
        # Composer install trên server để đảm bảo dependencies tương thích môi trường server
        run: |
          ssh ${{ secrets.SSH_USERNAME }}@${{ secrets.SSH_HOST }} "cd ${{ secrets.SSH_TARGET_DIR }} && composer install --no-dev --prefer-dist --optimize-autoloader"

      - name: Run Laravel commands on server
        run: |
          ssh ${{ secrets.SSH_USERNAME }}@${{ secrets.SSH_HOST }} "cd ${{ secrets.SSH_TARGET_DIR }} && \
          php artisan cache:clear && \
          php artisan config:cache && \
          php artisan route:cache && \
          php artisan view:cache && \
          php artisan migrate --force && \ # Cẩn trọng khi chạy migrations tự động
          php artisan storage:link && \ # Chỉ chạy nếu bạn dùng symbolic link cho storage
          chmod -R 775 ${{ secrets.SSH_TARGET_DIR }}/storage && \
          chmod -R 775 ${{ secrets.SSH_TARGET_DIR }}/bootstrap/cache"
        env:
          # Đảm bảo các biến môi trường cần thiết được truyền cho Artisan commands
          # Hoặc đảm bảo .env file đã được cấu hình trên server
          APP_ENV: production
          APP_DEBUG: false
          # DATABASE_URL: ${{ secrets.DB_URL }} # Nếu bạn muốn truyền biến DB từ secrets
          # APP_KEY: ${{ secrets.APP_KEY }} # Nếu bạn lưu APP_KEY trong secrets

      - name: Clear Laravel logs (Optional)
        run: |
          ssh ${{ secrets.SSH_USERNAME }}@${{ secrets.SSH_HOST }} "cd ${{ secrets.SSH_TARGET_DIR }} && \
          rm -rf storage/logs/*"

IV. Giải thích và Điều chỉnh Quan trọng

  1. SSH_PRIVATE_KEY và SSH_PASSPHRASE Secrets:

    • Đây là cách an toàn để lưu trữ Private Key của bạn.
    • Lưu ý: Chỉ thêm SSH_PASSPHRASE nếu Private Key của bạn có mật khẩu. Nếu không, hãy bỏ dòng đó trong workflow.

  2. SSH_TARGET_DIR:

    • Rất quan trọng! Đường dẫn này phải là đường dẫn tuyệt đối đến thư mục gốc của dự án Laravel trên cPanel của bạn. Nó thường bắt đầu bằng /home/yourcpanelusername/ rồi đến thư mục dự án (ví dụ: /home/cpaneluser/public_html/my-laravel-app). Bạn có thể tìm đường dẫn này trong File Manager của cPanel hoặc bằng cách chạy lệnh pwd qua SSH khi đang ở thư mục gốc của dự án.

  3. php-version: Đảm bảo phiên bản PHP trong workflow (php-version: '8.2') khớp với phiên bản PHP bạn đã chọn trên cPanel.

  4. composer install:

    • Workflow này chạy composer install hai lần:
      • Một lần trên GitHub Actions runner (Install Composer dependencies locally): Điều này chỉ để đảm bảo rằng các file PHP của project được đóng gói đầy đủ (nếu bạn dùng rsync để upload file).
      • Một lần trên server (Run Composer Install on server): Đây là bước quan trọng nhất. Nó đảm bảo rằng thư mục vendor/ được tạo ra trên server với các gói dependencies tương thích với môi trường server của cPanel. Chúng ta loại trừ thư mục vendor/ khỏi rsync để đảm bảo Composer chạy đúng trên server.

  5. .env file:

    • Tuyệt đối KHÔNG commit file .env vào GitHub.
    • Bạn cần tạo file .env trên cPanel của mình thủ công lần đầu tiên và điền các thông tin database, APP_KEY, mail settings, v.v.
    • APP_KEY: Sau khi deploy lần đầu, bạn cần chạy php artisan key:generate trên cPanel (thủ công qua SSH) để tạo APP_KEY và cập nhật vào .env. Các lần deploy sau chỉ cần đảm bảo .env đã có trên server.
    • Các biến môi trường trong phần env: của bước "Run Laravel commands on server" chỉ dùng để ghi đè tạm thời hoặc bổ sung cho .env đã có trên server.

  6. rsync:

    • Đây là công cụ đồng bộ hóa file hiệu quả, chỉ upload những file đã thay đổi.
    • --delete: Cực kỳ cẩn trọng với tùy chọn này! Nó sẽ xóa các file trên server mà không còn tồn tại trong local repository của bạn. Hãy đảm bảo bạn đã cấu hình exclude chính xác để không xóa nhầm các file quan trọng được tạo ra trên server (ví dụ: user uploads trong storage/app/public hoặc các file log).
    • exclude: Danh sách các thư mục và file không cần upload lên server.

  7. Laravel Commands trên Server:

    • php artisan cache:clear, config:cache, route:cache, view:cache: Các lệnh này giúp tối ưu hóa Laravel cho môi trường production.
    • php artisan migrate --force: Rất quan trọng và cần cẩn trọng. Lệnh này sẽ chạy các migrations chưa được chạy. Đảm bảo bạn đã sao lưu database trước khi chạy tự động trên production.
    • php artisan storage:link: Tạo symbolic link cho thư mục storage/app/public ra public/storage. Điều này yêu cầu quyền SSH và là một lệnh cần thiết nếu bạn lưu trữ file user upload.
    • chmod -R 775 storage và chmod -R 775 bootstrap/cache: Đảm bảo quyền ghi cho các thư mục này. Quyền 775 là một lựa chọn tốt cho hầu hết các shared host, cho phép PHP-FPM/Apache ghi vào.

V. Các bước sau khi Deploy lần đầu

  1. Cấu hình .env lần đầu:
    • Đăng nhập SSH vào cPanel của bạn.
    • Di chuyển đến thư mục gốc của dự án (cd /home/cpaneluser/public_html/my-laravel-app).
    • Tạo file .env nếu chưa có: cp .env.example .env.
    • Chỉnh sửa file .env bằng trình soạn thảo dòng lệnh (ví dụ: nano .env hoặc vi .env). Điền đầy đủ thông tin database, mail, và các biến môi trường khác.
    • Tạo APP_KEY: Chạy php artisan key:generate. Lệnh này sẽ tạo một APP_KEY mới và tự động cập nhật vào file .env.
  2. Chạy Migrations (nếu cần): Nếu bạn không muốn chạy migrate --force tự động trong CI/CD, bạn có thể chạy thủ công qua SSH: php artisan migrate.
  3. Kiểm tra và theo dõi Workflow: Sau khi push code lên branch đã cấu hình, vào mục "Actions" trên GitHub repository của bạn để xem workflow đang chạy và kiểm tra kết quả.

Với setup này, mỗi khi bạn đẩy code lên branch main (hoặc branch bạn đã cấu hình), GitHub Actions sẽ tự động SSH vào cPanel, đồng bộ hóa code, cài đặt dependencies, chạy các lệnh Laravel và deploy dự án của bạn!

Tags:

Post a Comment

Previous Post Next Post