Cài đặt và cấu hình Jigsaw trong môi trường ServBay

Tổng quan

Tài liệu này hướng dẫn bạn cách cài đặt và cấu hình Jigsaw - một trình tạo website tĩnh mạnh mẽ dựa trên Laravel - trong môi trường phát triển web nội bộ ServBay. ServBay cung cấp môi trường tích hợp cho các stack công nghệ như PHP, Node.js, giúp đơn giản hóa quá trình thiết lập dự án Jigsaw đáng kể. Với ServBay, bạn dễ dàng cấu hình tên miền nội bộ, HTTPS và máy chủ web hiệu quả cho dự án Jigsaw, từ đó tập trung phát triển nội dung website.

Jigsaw là gì?

Jigsaw là một trình tạo website tĩnh được phát triển bởi Tighten, xây dựng trên các thành phần của Laravel. Công cụ này tận dụng sức mạnh và sự linh hoạt của engine template Laravel Blade, kết hợp với các tập tin Markdown để tạo ra các website HTML tĩnh thuần túy. Jigsaw rất phù hợp để xây dựng các website tài liệu, blog, trang giới thiệu sản phẩm hoặc bất kỳ website nào không cần cơ sở dữ liệu phía sau và không xử lý động trên server. Các ưu điểm nổi bật của Jigsaw gồm:

• Khai thác công cụ quen thuộc: Nếu bạn đã quen với Laravel hoặc Blade template, việc sử dụng Jigsaw sẽ rất nhanh chóng.
• Hiệu năng & bảo mật: Website tĩnh được tạo ra tải cực nhanh và an toàn tuyệt đối vì không có code server nào được thực thi.
• Template linh hoạt: Template Blade cho phép tạo layout và component phức tạp một cách dễ dàng.
• Hỗ trợ Markdown: Viết nội dung thuận tiện và chuẩn SEO.

Các trường hợp ứng dụng

Bạn nên cân nhắc sử dụng Jigsaw cho những trường hợp sau:

• Website tài liệu dự án hoặc tài liệu API
• Blog cá nhân, chia sẻ kỹ thuật
• Trang landing page giới thiệu doanh nghiệp, sản phẩm
• Website giới thiệu nhỏ
• Mọi website có nội dung ít thay đổi, đề cao hiệu năng và bảo mật

Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo các điều kiện sau:

1. Đã cài đặt và chạy ServBay: Bạn cần cài ServBay trên macOS và đảm bảo ServBay đã khởi động. ServBay tích hợp sẵn PHP, Composer, Node.js/npm – đây là các thành phần bắt buộc để cài và chạy Jigsaw.
2. Kiến thức cơ bản về dòng lệnh: Sử dụng terminal để thực hiện một số lệnh cần thiết.
3. Hiểu biết ngắn gọn về Composer và npm: Cài đặt Jigsaw dựa trên Composer, còn biên dịch tài sản frontend dùng npm.

Các bước cài đặt & cấu hình

Phần này sẽ hướng dẫn chi tiết từng bước để thiết lập dự án Jigsaw trong môi trường ServBay.

Bước 1: Tạo thư mục dự án

Đầu tiên, mở Terminal, chuyển vào thư mục gốc website do ServBay khuyến nghị: /Applications/ServBay/www, và tạo thư mục con cho dự án Jigsaw của bạn.

cd /Applications/ServBay/www
mkdir servbay-jigsaw-demo
cd servbay-jigsaw-demo

Ta đặt tên thư mục dự án là servbay-jigsaw-demo. Toàn bộ mã nguồn sẽ được lưu ở đây.

Bước 2: Tạo dự án Jigsaw với Composer

ServBay đã cài sẵn Composer, bạn có thể dùng lệnh composer ở bất cứ cửa sổ terminal nào. Chạy lệnh sau trong thư mục dự án vừa tạo (/Applications/ServBay/www/servbay-jigsaw-demo) để khởi tạo dự án Jigsaw:

composer create-project tightenco/jigsaw .

Lệnh này sẽ tải về phiên bản Jigsaw mới nhất và toàn bộ dependency PHP cần thiết vào thư mục hiện tại (.). Lưu ý dấu . ở cuối nghĩa là sẽ tạo dự án ngay trong thư mục hiện tại, không tạo thêm thư mục con jigsaw.

Bước 3: Cấu hình website trong ServBay

Để truy cập website Jigsaw qua trình duyệt, bạn cần cấu hình một website nội bộ trong ServBay.

1. Mở giao diện ServBay: Bấm đúp biểu tượng ServBay hoặc sử dụng icon trên thanh menu để vào bảng điều khiển.
2. Đi đến mục “Website”: Trong thanh navigation bên trái, chọn tab “Website”.
3. Thêm website mới: Bấm nút “+” ở cuối giao diện, chọn “Thêm website”.
4. Điền thông tin chi tiết cho website:
   • Tên (Name): Đặt tên dễ nhận biết cho dự án, ví dụ ServBay Jigsaw Demo.
   • Tên miền (Domain): Nhập tên miền nội bộ mà bạn muốn sử dụng. Khuyến nghị dùng hậu tố .servbay.demo để tránh trùng với tên miền thật, như jigsaw-demo.servbay.demo. ServBay sẽ tự động ánh xạ miền này về localhost.
   • Loại website (Site Type): Chọn PHP vì quá trình build Jigsaw cần môi trường PHP.
   • Phiên bản PHP (PHP Version): Chọn phiên bản PHP đã cài trong ServBay, khuyến nghị dùng bản mới và ổn định nhất.
   • Thư mục gốc (Site Root): Đây là bước cực kỳ quan trọng. Các file tĩnh do Jigsaw build ra sẽ nằm trong thư mục build_local ở root dự án. Vì vậy, hãy trỏ thư mục gốc website về: /Applications/ServBay/www/servbay-jigsaw-demo/build_local
5. Lưu và áp dụng: Điền xong, nhấn “Lưu”. ServBay sẽ yêu cầu xác nhận, nhấn đồng ý để áp dụng thay đổi. ServBay sẽ tự động cập nhật cấu hình máy chủ web (Caddy hoặc Nginx), đồng thời cấu hình HTTPS cho tên miền vừa khai báo.

Bước 4: Cài đặt dependency frontend

Dự án Jigsaw thường dùng npm để quản lý, biên dịch các tài sản frontend như SASS, JavaScript... ServBay đã tích hợp sẵn Node.js và npm.

Trong thư mục dự án (/Applications/ServBay/www/servbay-jigsaw-demo), chạy lệnh sau để cài các gói npm cần thiết:

npm install

Lệnh này sẽ đọc file package.json trong thư mục dự án và tải về các module Node.js vào folder node_modules.

Bước 5: Biên dịch website Jigsaw

Sau khi đã cài đủ dependency, bạn cần chạy lệnh build của Jigsaw để tạo ra file tĩnh của website.

Vào thư mục dự án, chạy:

./vendor/bin/jigsaw build

Lệnh trên sẽ thực hiện những việc sau:

1. Xử lý các file Markdown và template Blade trong thư mục source.
2. Chạy các task biên dịch định nghĩa trong webpack.mix.js (nếu đã dùng Laravel Mix với npm install).
3. Xuất toàn bộ HTML, CSS, JS cùng asset tĩnh vào thư mục build_local.

Bước 6: Truy cập website

Giờ đây, file tĩnh đã được build ra thư mục /Applications/ServBay/www/servbay-jigsaw-demo/build_local. Vì website đã trỏ root về đây, bạn chỉ cần mở trình duyệt và truy cập tên miền đã cấu hình.

Mở trình duyệt, nhập domain như https://jigsaw-demo.servbay.demo. ServBay sẽ tự động xử lý chứng chỉ HTTPS (dùng ServBay User CA), và bạn sẽ thấy trang chào mừng mặc định của Jigsaw.

Tùy biến và phát triển

Bạn đã hoàn tất môi trường nền tảng – đã đến lúc tùy chỉnh nội dung và giao diện website Jigsaw!

Chỉnh sửa nội dung và template

• Source code website nằm trong thư mục source tại root dự án.
• Layout và component HTML viết bằng Blade đặt ở các thư mục con như source/_layouts, source/_partials.
• Nội dung trang thường viết với Markdown, nằm ở thư mục source hoặc các thư mục con (ví dụ: source/index.md, source/about.md).
• Bài viết blog thường nằm ở source/_posts theo định dạng tên file YYYY-MM-DD-slug.md.

Thêm trang mới/bài viết mới

Muốn thêm trang hoặc bài blog, chỉ cần tạo file Markdown mới trong thư mục source hoặc source/_posts tương ứng.

Ví dụ, tạo một file source/about.md:

---
title: "Giới thiệu"
description: "Tìm hiểu thêm về ServBay Jigsaw Demo"
---

# Giới thiệu

Đây là trang giới thiệu được xây dựng bằng Jigsaw.

Tại đây, bạn có thể thêm phần giới thiệu công ty, thông tin nhóm, v.v.

Tùy biến CSS và JavaScript

Dự án Jigsaw thường dùng Laravel Mix (webpack.mix.js) để biên dịch asset frontend.

• File CSS/SASS thường đặt ở source/_assets/sass
• JS ở source/_assets/js

Tại root dự án, bạn sử dụng npm script để biên dịch asset:

• npm run dev: Biên dịch asset cho môi trường phát triển, đi kèm Source Maps, không nén.
• npm run watch: Biên dịch asset và tự động lắng nghe thay đổi files, rất hữu ích khi đang phát triển.
• npm run prod: Biên dịch asset cho môi trường production, sẽ nén và tối ưu tối đa.

Ví dụ, sau khi chỉnh sửa source/_assets/sass/main.scss, bạn hãy chạy npm run dev hoặc npm run watch để build lại CSS.

Build lại website

Lưu ý quan trọng: Sau mỗi lần sửa nội dung ở thư mục source (file Markdown hoặc Blade template), bạn cần build lại website bằng lệnh:

./vendor/bin/jigsaw build

Nếu bạn đã sửa asset frontend (SASS, JS), cần chạy npm run dev hoặc npm run watch để biên dịch lại asset này. Đa số dự án Jigsaw, lệnh build cũng sẽ kích hoạt Mix compile, nhưng hiểu điều này sẽ giúp bạn dễ debug.

Một số lưu ý

• Thư mục đầu ra: Jigsaw mặc định build ra build_local (cho phát triển) và build_production (cho production). Hãy đảm bảo website ServBay trỏ đúng folder bạn muốn truy cập (phát triển thường dùng build_local).
• Máy chủ web: ServBay dùng Caddy hoặc Nginx và phục vụ file tĩnh trực tiếp từ build_local, rất hiệu quả. Bạn không cần dùng lệnh jigsaw serve nội bộ (chủ yếu dùng preview nhanh, không mạnh bằng máy chủ ServBay).
• HTTPS: ServBay tự động cấu hình HTTPS cho domain .servbay.demo và cấp chứng chỉ từ ServBay User CA. Có thể bạn phải tin cậy CA này trong hệ thống để tránh cảnh báo từ trình duyệt.
• Build sạch: Nếu xuất hiện lỗi build bất thường, thử chạy ./vendor/bin/jigsaw build --clean để build lại từ đầu.

Câu hỏi thường gặp (FAQ)

Q: Tôi đã sửa file Markdown, sao trình duyệt không cập nhật nội dung?

A: Bạn cần chạy lại lệnh ./vendor/bin/jigsaw build sau khi thay đổi nội dung hay template để build lại website.

Q: Đã sửa file SCSS, nhưng style vẫn không thay đổi?

A: Sau khi chỉnh sửa file frontend asset, hãy chạy npm run dev hoặc npm run watch trong thư mục dự án để biên dịch lại asset.

Q: Truy cập tên miền nội bộ báo “Không thể truy cập” hoặc “Không tìm thấy file”?

A: Hãy kiểm tra các điểm sau:

1. Đảm bảo ServBay đang chạy.
2. Xem lại cấu hình website trong ServBay: Tên miền đã đúng chưa? Thư mục gốc có trỏ về /Applications/ServBay/www/servbay-jigsaw-demo/build_local chưa?
3. Đảm bảo lệnh ./vendor/bin/jigsaw build đã chạy thành công, thư mục build_local đã có file tĩnh như index.html chưa.

Q: Deploy website Jigsaw như thế nào?

A: Jigsaw tạo ra website tĩnh thuần. Thường, bạn:

1. Chạy ./vendor/bin/jigsaw build production để build file cho production (tối ưu hơn).
2. Upload toàn bộ file trong build_production lên bất kỳ dịch vụ hosting nào hỗ trợ website tĩnh (Netlify, Vercel, GitHub Pages, lưu trữ đám mây...).

Tổng kết

Với ServBay, việc cài đặt và cấu hình Jigsaw trên macOS trở nên cực kỳ nhanh chóng và hiệu quả. ServBay tích hợp đủ môi trường cần thiết (PHP, Composer, Node.js, npm) cùng khả năng cấu hình máy chủ web địa phương mạnh mẽ. Làm theo hướng dẫn này, bạn sẽ triển khai dự án Jigsaw nhanh chóng và dễ dàng tận dụng các tính năng của ServBay để tối ưu quy trình phát triển website nội bộ của mình.