Deploy dự án Laravel lên cPanel bằng GitHub Actions

byKhông Nên Tin •
0

Deploy dự án Laravel lên cPanel bằng GitHub Actions là một giải pháp tự động hóa tuyệt vời, giúp bạn tiết kiệm thời gian và giảm thiểu lỗi. Quy trình này sẽ đẩy code từ GitHub repository của bạn lên hosting cPanel thông qua FTP/SFTP.



Dưới đây là hướng dẫn chi tiết từng bước:

I. Chuẩn bị trên cPanel

  1. Tạo Tài khoản FTP/SFTP:

    • Đăng nhập vào cPanel của bạn.
    • Tìm mục "Files" (Tập tin) và chọn "FTP Accounts" (Tài khoản FTP).
    • Tạo một tài khoản FTP mới với:
      • Login (Tên đăng nhập): Ví dụ: githubdeploy
      • Password (Mật khẩu): Mật khẩu mạnh.
      • Directory (Thư mục): Rất quan trọng! Chọn thư mục gốc của dự án Laravel trên cPanel.
        • Nếu bạn muốn deploy vào thư mục public_html, hãy để trống hoặc chọn /public_html.
        • Nếu dự án của bạn nằm trong một thư mục con, ví dụ public_html/my-laravel-app, hãy chỉ định /public_html/my-laravel-app.
      • Quota (Hạn mức): Unlimited hoặc đủ lớn.
    • Ghi lại Tên đăng nhập FTP, Mật khẩu FTP, Máy chủ FTP (Hostname/IP). Thông thường, Hostname sẽ là tên miền của bạn (ví dụ: yourdomain.com hoặc ftp.yourdomain.com).

  2. 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 phiên bản 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).

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

    • Để Laravel hoạt động đúng với cấu trúc bảo mật (thư mục public là nơi truy cập công khai), bạn cần trỏ Document Root của tên miền (hoặc subdomain) về thư mục public của dự án Laravel.
    • Trong cPanel, tìm mục "Domains" (Tên miền) và chọn "Domains" hoặc "Subdomains" tùy vào cách bạn thiết lập.
    • 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 đăng nhập FTP 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:
      • FTP_HOST: Giá trị là địa chỉ máy chủ FTP của bạn (ví dụ: yourdomain.com).
      • FTP_USERNAME: Giá trị là tên đăng nhập FTP bạn đã tạo.
      • FTP_PASSWORD: Giá trị là mật khẩu FTP bạn đã tạo.
      • FTP_PATH: Giá trị là đường dẫn đến thư mục gốc của dự án trên cPanel (ví dụ: /public_html/my-laravel-app hoặc /public_html).

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.yml.

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

    YAML
    name: Deploy Laravel to cPanel

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

jobs:
  web-deploy:
    name: Deploy
    runs-on: ubuntu-latest

    steps:
      - name: Get latest code
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2' # Đảm bảo phiên bản PHP này khớp với cPanel của bạn
          extensions: pdo_mysql, mbstring, tokenizer, xml, ctype, json, bcmath, 
  3.           fileinfo, curl
          ini-values: post_max_size=256M, upload_max_filesize=256M
          tools: composer:v2 # Cài đặt Composer v2

      - name: Install Composer dependencies
        run: composer install --no-dev --prefer-dist --optimize-autoloader

      - name: Generate .env file (assuming .env is NOT committed)
        run: |
          cp .env.example .env # Hoặc tạo .env từ template khác nếu cần
          # Thêm các biến môi trường cần thiết cho production vào .env
          # Ví dụ: echo "APP_ENV=production" >> .env
          # echo "APP_DEBUG=false" >> .env
          # echo "APP_KEY=${{ secrets.APP_KEY }}" >> .env 
  4. # Nếu bạn lưu APP_KEY trong GitHub Secrets
  5.           # Nếu bạn không muốn tạo .env ở đây, 
  6. # bạn sẽ phải cấu hình nó thủ công trên cPanel HOẶC dùng cPanel
    # Environment Variables
    
      - name: Run migrations & seeders (Optional - Use with caution!)
        # Lưu ý: Chạy migrations trên môi trường production có thể phức tạp.
        # Đảm bảo bạn đã sao lưu database và hiểu rõ hậu quả.
        # Đối với một số shared hosting, bạn có thể cần chạy thủ công qua 
  7.    # SSH/Terminal của cPanel.
  8.         # Nếu bạn không có SSH, bạn cần bỏ qua bước này và chạy thủ công qua 
  9.         # PHPMyAdmin/cPanel SQL.
        # run: php artisan migrate --force
        # run: php artisan db:seed --force # Chỉ khi cần

      - name: Cache config and routes
        run: |
          php artisan config:cache
          php artisan route:cache
          php artisan view:cache

      - name: Upload project to FTP
        uses: SamKirkland/FTP-Deploy-Action@v4.3.0
        with:
          server: ${{ secrets.FTP_HOST }}
          username: ${{ secrets.FTP_USERNAME }}
          password: ${{ secrets.FTP_PASSWORD }}
          server-dir: ${{ secrets.FTP_PATH }}/ # Đảm bảo có dấu gạch chéo ở cuối
          # Lọc các file/thư mục không cần thiết để upload
          exclude: |
            .git/
            .github/
            node_modules/
            vendor/ # Composer sẽ chạy trên server
            .env # Không upload .env từ GitHub, bạn sẽ tạo nó trên cPanel
            storage/ # Không upload storage, trừ khi có cấu hình đặc biệt
            *.md
            .gitignore
            composer.json
            composer.lock
            package.json
            package-lock.json
            webpack.mix.js
            postcss.config.js
            tailwind.config.js
            # Thêm bất kỳ file/folder nào bạn không muốn upload
            # delete-excluded: true # Xóa các file/folder không nằm trong 
  10.             # exclude trên server (CỰC KỲ CẨN TRỌNG VỚI CÁI NÀY!)

      - name: Run post-deployment commands (Optional - via SSH, if available)
        # Nếu shared hosting của bạn có SSH, bạn có thể dùng 
  11.         # SSH action để chạy các lệnh Artisan cuối cùng
        # Ví dụ: php artisan migrate --force, php artisan storage:link, etc.
        # uses: appleboy/ssh-action@master
        # with:
        #   host: ${{ secrets.FTP_HOST }}
        #   username: ${{ secrets.FTP_USERNAME }}
        #   key: ${{ secrets.SSH_PRIVATE_KEY }} 
  12.         # Bạn cần tạo SSH key và thêm vào GitHub Secrets
        #   script: |
        #     cd ${{ secrets.FTP_PATH }}
        #     php artisan migrate --force
        #     php artisan storage:link

      - name: Set permissions (Optional - if needed and possible via FTP/SSH)
        # Một số host cần chmod cho thư mục storage và bootstrap/cache
        # run: |
        #   chmod -R 755 ${{ secrets.FTP_PATH }}/storage
        #   chmod -R 775 ${{ secrets.FTP_PATH }}/bootstrap/cache
        #   chmod -R 777 ${{ secrets.FTP_PATH }}/storage # Cực kỳ cẩn trọng với 777

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

  1. Branch main: Dòng branches: - main nghĩa là workflow sẽ chạy mỗi khi có commit mới được đẩy lên branch main. Thay đổi thành branch bạn muốn deploy (ví dụ: production).

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

  3. Composer Dependencies (composer install --no-dev --prefer-dist --optimize-autoloader):

    • Workflow này sẽ cài đặt các dependencies (các thư viện trong vendor/) ngay trên GitHub Actions runner.
    • Bạn KHÔNG nên upload thư mục vendor/ lên FTP. Thay vào đó, bạn upload các file code Laravel, sau đó chạy composer install --no-dev trên cPanel (nếu có SSH) hoặc đơn giản là để GitHub Actions cài đặt vendor/ và sau đó upload tất cả thư mục project bao gồm vendor/.
    • Trong ví dụ trên, vendor/ đã được cài đặt trên GitHub Actions runner và sau đó được upload lên FTP cùng với các file khác. Đây là cách đơn giản nhất nếu cPanel của bạn không có SSH hoặc Composer.

  4. .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, bạn cần chạy php artisan key:generate trên cPanel (nếu có SSH) hoặc copy giá trị APP_KEY từ local vào .env trên cPanel.
    • Trong workflow, cp .env.example .env là một cách đơn giản, nhưng bạn sẽ cần thêm các biến môi trường thực tế vào file .env được tạo ra đó. Cách an toàn hơn là cấu hình .env trực tiếp trên cPanel và KHÔNG tạo nó trong GitHub Actions workflow.

  5. Migrations & Seeders:

    • Mặc định, các shared hosting cPanel không cung cấp quyền SSH để bạn chạy php artisan migrate dễ dàng.
    • Nếu bạn có SSH, hãy thêm bước "Run post-deployment commands" như trong ví dụ.
    • Nếu không có SSH, bạn sẽ phải chạy migrations thủ công thông qua phpMyAdmin hoặc tính năng Terminal/Cron Jobs của cPanel (nếu có hỗ trợ).
    • Thận trọng cực kỳ khi chạy php artisan migrate --force tự động, đặc biệt nếu có dữ liệu quan trọng. Luôn sao lưu database trước.

  6. SamKirkland/FTP-Deploy-Action:

    • server-dir: Đảm bảo đường dẫn này khớp với thư mục mà tài khoản FTP của bạn trỏ đến.
    • exclude: Rất quan trọng để loại trừ các file/thư mục không cần thiết hoặc nhạy cảm (như .git, .github, node_modules, vendor, .env).
    • delete-excluded: true: Cực kỳ cẩn trọng với tùy chọn này. Nó sẽ xóa tất cả các file/thư mục trên server mà không nằm trong danh sách exclude. Nếu bạn có bất kỳ file nào được tạo ra trên server (ví dụ: user uploads trong storage/app/public hoặc storage/logs), tùy chọn này có thể xóa chúng. Thường thì nên để mặc định (false) hoặc chỉ bật khi bạn chắc chắn.

  7. storage:link:

    • Nếu bạn sử dụng php artisan storage:link để tạo symbolic link cho thư mục storage/app/public ra public/storage, bạn cần chạy lệnh này trên cPanel.
    • Điều này thường yêu cầu quyền SSH. Nếu không có SSH, bạn có thể phải cấu hình web server (Apache/Nginx) để trỏ trực tiếp đến storage/app/public (ít phổ biến trên cPanel) hoặc copy thủ công các file từ storage/app/public sang public/storage sau mỗi lần deploy (không được tự động).

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

  1. Cấu hình .env: Đăng nhập vào cPanel, vào "File Manager", điều hướng đến thư mục gốc của dự án Laravel (ví dụ: /public_html/my-laravel-app), và tạo/chỉnh sửa file .env. Điền đầy đủ thông tin database, APP_KEY, mail settings, v.v. Cực kỳ quan trọng là APP_KEY phải được tạo bằng php artisan key:generate (nếu có SSH) hoặc copy từ local.
  2. Chạy Migrations (nếu chưa chạy tự động): Nếu bạn không chạy php artisan migrate --force trong workflow, hãy chạy nó thủ công (qua SSH nếu có, hoặc qua công cụ Terminal/PHPMyAdmin của cPanel).
  3. Tạo Symbolic Link cho Storage (nếu cần): Nếu bạn sử dụng storage:link và host hỗ trợ SSH, chạy php artisan storage:link. Nếu không, bạn cần cân nhắc cách xử lý các file public trong storage/app/public.

Thực hiện theo các bước này, bạn sẽ có một quy trình CI/CD tự động cơ bản để deploy dự án Laravel của mình lên cPanel bằng GitHub Actions.

Tags:

Post a Comment

Previous Post Next Post