Computer >> Hướng Dẫn Máy Tính >  >> Lập Trình >> Lập Trình Bash

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Khi làm việc trên dự án có nhiều môi trường – như staging và production – cho backend API và frontend deployment, bạn muốn đảm bảo cấu hình và lệnh đúng cho từng nhánh trong repository.

Điều này trở nên khó khăn khi nhiều dev cùng làm việc trên codebase, thay đổi nhánh khác nhau, hoặc quản lý nhiều cấu hình riêng cho từng nhánh.

Giống như mọi pull request hoặc thay đổi push lên nhánh, bạn cần review từng dòng code bị thay đổi, thêm, xóa trước khi quyết định merge. File cấu hình trong codebase không ngoại lệ, dễ dẫn đến lỗi vì một thay đổi nhỏ có thể ảnh hưởng toàn bộ thiết lập Continuous Integration.

Khi thay đổi được push lên nhánh staging hoặc production và build được kích hoạt, bạn muốn đảm bảo tài nguyên đúng cho nhánh đó được duy trì. Trong một số trường hợp, bạn cần định nghĩa quy tắc redirect khác nhau cho từng client, lệnh build tùy chỉnh, hoặc cài đặt khác cho từng nhánh.

Trong bài này, tôi sẽ hướng dẫn cách quản lý cấu hình riêng cho từng nhánh (bao gồm redirect cho nhiều nhánh) tự động, dùng script Bash đơn giản. Cũng sẽ chỉ cách merge an toàn các quy tắc theo ngữ cảnh cho nhánh staging và production trên Netlify.

Nội dung bao gồm:

  • Cấu trúc dự án và tình huống

  • Redirect/Rewrite là gì?

  • Netlify xử lý Redirect như thế nào?

    • Cú pháp file _redirects

    • Cú pháp file cấu hình netlify.toml

  • Vấn đề: Quản lý nhiều file netlify.toml cho nhánh khác nhau

  • Cách viết script tự động tạo file cấu hình

    • File Netlify.toml mẫu

    • Bước 1: Tạo thư mục script và thêm file script

    • Bước 2: Sửa package.json để thêm lệnh script

  • Cách deploy client lên Netlify

    • Triển khai lần đầu dự án lên Netlify

    • Triển khai tiếp theo / Cách thiết lập Branch Deployments

      • Bước 1: Thiết lập Environment Variables trên Netlify cho từng ngữ cảnh – production, staging, v.v.

      • Bước 2: Kích hoạt deploy mới

  • Kiểm tra Deployments

  • Kết luận

Cấu trúc dự án và tình huống

Xét tình huống: bạn có 2 server riêng cho dự án: một phục vụ môi trường staging (deploy trên Render), một cho production (deploy trên Google Cloud Run).

Bạn cũng có 2 client deployment riêng trên Netlify, mỗi cái với API_BASE_URL riêng, được phục vụ bởi server tương ứng như hình minh họa:

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Hình dưới là repository sample-project với thư mục api và client. Tổng quan cấu trúc trong các nhánh. Mỗi thư mục có package.json riêng, được xem như thành phần độc lập, có thể deploy lên 2 dịch vụ riêng.

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Trong frontend deployment cho từng client, tất cả request đến endpoint bắt đầu bằng /api/v1/ được route đến server. Các route khác giữ nguyên trong frontend để điều hướng trang. Do đó bạn cần viết quy tắc đúng để client biết cách xử lý request. Đây gọi là redirect rules hoặc rewrites.

Redirect/Rewrite là gì?

Redirect (hay rewrite) là quy tắc cho phép URL tự động chuyển đến vị trí mới bất kỳ trên internet (nguồn: WPengine). Còn gọi là URL forwarding, dùng được cho toàn bộ website, một phần website, hoặc toàn bộ web app.

Trong web app, redirect thường dùng để quyết định cách xử lý request. Nền tảng hosting như Netlify, Vercel cung cấp tùy chọn này để dev xác định cách web app xử lý request.

Netlify xử lý Redirect như thế nào?

Netlify có 2 cách chỉ định redirect rules: dùng cú pháp file _redirects hoặc file cấu hình netlify.toml. Cả hai đạt cùng mục tiêu, nhưng netlify.toml cho nhiều tùy chọn và khả năng hơn.

Dùng cú pháp file _redirects

Nếu chọn cách này, chỉ cần tạo file _redirects trong thư mục public của client app, viết quy tắc redirect bên trong. Rất đơn giản. Ví dụ quy tắc redirect trong file:

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Quy tắc trên nghĩa là:

  1. Gửi tất cả request khớp /api/v1 đến API URL chỉ định, trả về status 200. Dấu sao (*) sau /api/v1/ như trong /api/v1/* chỉ việc nối phần mở rộng URL gốc vào API URL. Ví dụ route /api/v1/users trên frontend sẽ redirect đến https://your-api-base-url.com/api/v1/users. :splat trong API URL chỉ placeholder.

  2. Phục vụ các route mặc định khác qua thư mục index.html. Cần thiết để tránh trang bị lỗi khi điều hướng trang khác và quay lại bằng nút "back".

Dùng cú pháp file cấu hình netlify.toml

File netlify.toml cho nhiều linh hoạt hơn khi chỉ định redirect rules, bao gồm match route gốc, đích đến, status code, header rules, signatures, giới hạn quốc gia, roles, v.v.

File netlify.toml mẫu từ tài liệu Netlify:

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Lưu ý nhanh: Dùng file redirects để redirect request đến API hoàn toàn ổn. Nhưng coi như rủi ro bảo mật nếu để API URL dạng plain text trong file redirects khi API_BASE_URL nên giữ bí mật. Vì file trong public folder là công khai – ai cũng truy cập được.

Nếu URL đích là public, dùng _redirects thoải mái. Nhưng nếu muốn URL riêng tư, dùng netlify.toml kết hợp environment variables an toàn hơn.

Vấn đề: Quản lý nhiều netlify.toml cho nhánh khác nhau

Khi dùng netlify.toml định nghĩa lệnh build và cài đặt môi trường, và bạn push thay đổi, mở pull request, bạn phải thủ công bỏ qua hoặc sửa từng netlify.toml trên mỗi nhánh. Điều này trở nên căng thẳng và dễ lỗi.

Ngoài ra, muốn tránh hardcode API URL trong _redirects hoặc netlify.toml trong codebase vì lý do bảo mật. Sẽ dùng environment variables từ Netlify UI cho production và staging.

Để tránh các vấn đề trên, sẽ dùng script nhỏ trong codebase để động tạo netlify.toml đúng cho từng nhánh. Cách này loại bỏ xung đột và không cần can thiệp thủ công khi chuyển nhánh hoặc xử lý pull request.

Cách viết script tự động tạo file cấu hình

File Netlify.toml mẫu

Dưới đây ảnh chụp file netlify.toml mẫu mà chúng ta muốn đạt được cho mỗi build. Tất cả request khớp api/v1/ trong codebase sẽ route đến API.

Bạn có thể cấu trúc endpoint API khác, ví dụ /api/your-endpoint – chỉ cần điều chỉnh script cho phù hợp. Dự án mẫu dùng api/v1/your-endpoint.

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Bước 1: Tạo thư mục script và thêm file script

Trong thư mục client, tạo thư mục scripts/ và file script configure-netlify.sh. Bắt buộc làm cho mỗi nhánh trong repo. Nội dung giống nhau.

Mở configure-netlify.sh và dán nội dung sau:

#!/bin/bash # Đảm bảo API_BASE_URL được thiết lập if [ -z "$API_BASE_URL" ]; then echo "Lỗi: Biến môi trường API_BASE_URL chưa được thiết lập." exit 1 # Dừng script để dừng deployment fi echo "Đang dùng API endpoint: $API_BASE_URL" # Định nghĩa cấu hình Netlify mong muốn NETLIFY_CONFIG=" [build] command = \"npm install && npm run build\" base = \"client\" publish = \"dist\" [[redirects]] from = \"/api/v1/*\" to = \"$API_BASE_URL/:splat\" status = 200 force = true [[redirects]] from = \"/*\" to = \"/index.html\" status = 200 " # Tạo hoặc cập nhật file netlify.toml if [ ! -f "netlify.toml" ]; then echo "Đang tạo file netlify.toml..." else echo "Đang cập nhật file netlify.toml hiện có..." fi echo "$NETLIFY_CONFIG" > netlify.toml # Xác nhận cấu hình thành công echo "File netlify.toml đã được cấu hình thành công!" 

Script thực hiện:

  1. Kiểm tra biến môi trường đảm bảo API_BASE_URL đã set. Nếu chưa, thoát build và gây fail. Đảm bảo không deploy thành công nhưng với URL sai trong production.

  2. Tạo nội dung netlify.toml như mẫu. Nếu endpoint API dùng cấu trúc khác api/v1/your-endpoint, điều chỉnh script cho phù hợp.

  3. Kiểm tra xem đã có netlify.toml chưa. Nếu chưa, tạo mới và ghi nội dung. Nếu có, cập nhật nội dung đúng trong lúc build, dùng API_BASE_URL từ environment variables.

Bước 2: Sửa package.json thêm lệnh script

Để tích hợp script vào quy trình build, thêm lệnh script vào package.json gọi script trước khi build thực sự.

Thêm lệnh configure-netlify như sau: "configure-netlify": "bash scripts/configure-netlify.sh" trong scripts của package.json.

Cập nhật lệnh build chạy script trước: "build": "npm run configure-netlify && vite build".

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Đừng quên lưu thay đổi và push lên remote repository.

Cách Deploy Client lên Netlify

Khi deploy client lên Netlify, có 3 tùy chọn:

  1. Import dự án có sẵn (từ git repo như GitHub, GitLab),

  2. Import từ template,

  3. Deploy thủ công static site qua Netlify drop (drag and drop).

Để cấu hình trong repo hoạt động đúng khi build, bạn bắt buộc dùng tùy chọn import từ dự án có sẵn (GitHub). Kéo thả không hoạt động. Nếu buộc phải dùng, hãy chọn cú pháp _redirects để định nghĩa redirect.

Triển khai lần đầu dự án lên Netlify

Lần đầu deploy, chỉ được deploy 1 nhánh ban đầu. Chỉ thêm nhánh khác ở các lần deploy sau.

Các bước deploy:

  1. Đăng nhập Netlify > netlify.com

  2. Click "Add new site" > "Import an existing project" > "Deploy with GitHub"

  3. Click "Configure Netlify on GitHub" > Tìm repository > Chọn

  4. Nhập tên site duy nhất

  5. Cấu hình deploy settings. Chọn nhánh deploy. Lần đầu sẽ deploy nhánh main (production branch).

    • Branch: main/master

    • Build command: npm run build

    • Publish directory: dist (Chọn thư mục chứa file tĩnh. Dự án mẫu export ra dist. Một số tool export ra build)

  6. Nhập environment variables cho dự án. Đừng quên API_BASE_URL từ server. Đây là yêu cầu bắt buộc theo script Bash.

  7. Click "Deploy site"

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Dự án sẽ deploy đúng, bạn thấy file netlify.toml do script tạo bằng cách xem chi tiết deployment ở dưới trang deploy thành công.

Có thể tải file về máy để xem cấu hình tạo ra. Nên khớp với file mẫu netlify.toml ở trên. Cũng test bằng link site generated.

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Triển khai tiếp theo / Cách thiết lập Branch Deployments

Bước 1: Thiết lập Environment Variables trên Netlify cho từng ngữ cảnh – production, staging, v.v.

Sau khi deploy thành công, có thể thiết lập deploy cho nhánh staging. Để chỉnh cấu hình:

  1. Vào danh sách sites

  2. Chọn site đã deploy thành công

  3. Click "site configuration" menu trái

  4. Chọn "environment variables" > click "Add a variable"

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Có tùy chọn thêm variable riêng lẻ hoặc import cả file .env. Chọn tùy ý. Hình dưới chọn "Import from a .env file".

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Vì production site (từ nhánh main với env production) đã deploy, bạn cần:

  1. Bỏ check production branch (để không ghi đè main branch ban đầu. Cẩn thận không lẫn env variables giữa nhánh)

  2. Chọn "branch deploys"

  3. Copy nội dung file .env vào ô nhập

  4. Đừng quên thêm API_BASE_URL cho môi trường staging

Lưu ý: chọn branch deploys nghĩa là env variables import ở đây ảnh hưởng tất cả branch deploys, trừ production branch. Có thể tùy chỉnh context bằng custom branch nhưng đó là cách khác, có thể cần tùy chỉnh thêm netlify.toml hoặc script Bash.

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Nếu import từng env variable riêng lẻ, có tùy chọn tương tự. Đảm bảo chọn đúng context cho từng nhánh.

KHÔNG DÙNG GIÁ TRỊ GIỐNG NHAU CHO TẤT CẢ CONTEXTS. Như hình dưới, chọn "different value for each deploy context" cho phép định nghĩa giá trị cho từng context. Ở đây định nghĩa cho branch deploys. Variable production ban đầu đã tồn tại.

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Sau khi import xong, kiểm tra bằng cách chọn dropdown bên phải mỗi variable xem giá trị.

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Bước 2: Kích hoạt deploy mới

Khi đã import xong env variables cho các context – production và staging – vào "deploys" panel trái. Click "Trigger deploy", clear cache, bắt đầu deploy mới.

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Kiểm tra Deployments

Xác nhận script hoạt động đúng bằng cách chọn deployment bất kỳ, chọn dropdown "building" trong "Deploy log". Sẽ thấy lệnh chạy, output và API URL cho deployment đó, theo context.

Tự động hóa cấu hình Netlify theo nhánh với Bash – Hướng dẫn từng bước

Kết luận

Làm theo các bước trong hướng dẫn, dùng script và lệnh cập nhật trên mỗi nhánh trong repo, khi push thay đổi Netlify sẽ tự động tạo hoặc cập nhật file netlify.toml trên mỗi nhánh. Điều này đảm bảo cấu hình đúng và environment variables cho từng môi trường được dùng tại build time.

Script giống nhau trên tất cả nhánh. Điều này giúp bạn tập trung vào thay đổi code khác mà script lo phần cấu hình an toàn, dễ dàng.

Hãy push thay đổi lên bất kỳ nhánh nào để thấy hoạt động.

Thoải mái kết nối với tôi trên Twitter (@francisihej) hoặc LinkedIn!

Học lập trình miễn phí. Chương trình mã nguồn mở của freeCodeCamp đã giúp hơn 40.000 người tìm việc lập trình viên. Bắt đầu ngay