ServBay

Tiếng Việt

English
简体中文
繁體中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Türkçe
Italiano

Tiếng Việt

English
简体中文
繁體中文
Español
العربية
Português
Русский
日本語
Deutsch
Français
Türkçe
Italiano

Appearance

Cài đặt và cấu hình Sculpin trên môi trường ServBay ​

Tổng quan ​

Sculpin là một trình tạo website tĩnh mạnh mẽ và linh hoạt dựa trên PHP, đặc biệt phù hợp cho việc xây dựng blog, website tài liệu hoặc bất kỳ dự án nào cần chuyển nội dung động (như template Twig và file Markdown) thành các trang HTML tĩnh hiệu suất cao. Sculpin sử dụng Composer để quản lý dependencies, được xây dựng dựa trên các component của Symfony, mang lại trải nghiệm phát triển quen thuộc và đáng tin cậy cho lập trình viên.

ServBay là môi trường phát triển web local dành riêng cho macOS, tích hợp sẵn nhiều phần mềm phổ biến như PHP, Composer, hệ quản trị cơ sở dữ liệu (MySQL, PostgreSQL, MongoDB, Redis), máy chủ web (Caddy, Nginx),... và giao diện quản lý đồ họa trực quan. Sử dụng ServBay giúp đơn giản hóa đáng kể quy trình thiết lập môi trường Sculpin trên macOS, đặc biệt là khi xử lý version PHP, quản lý dependencies, cũng như cấu hình máy chủ web.

Bài hướng dẫn này sẽ trình bày chi tiết cách cài đặt và cấu hình Sculpin trên môi trường ServBay, đồng thời thiết lập một website phát triển local.

Trường hợp sử dụng ​

  • Xây dựng blog tĩnh hiệu suất cao sử dụng PHP.
  • Sinh website tài liệu tĩnh cho dự án mã nguồn mở hoặc sản phẩm.
  • Nhanh chóng triển khai landing page marketing hoặc website doanh nghiệp không cần backend/database.
  • Viết nội dung bằng Twig và Markdown, tận hưởng tốc độ và bảo mật của site tĩnh.

Yêu cầu trước khi bắt đầu ​

Vui lòng đảm bảo đã đáp ứng các điều kiện sau:

  1. Đã cài đặt và chạy ServBay trên macOS. ServBay cung cấp đầy đủ môi trường PHP, Composer và máy chủ web (Caddy hoặc Nginx) cần thiết.
  2. Có kiến thức cơ bản về sử dụng dòng lệnh.
  3. Hiểu các khái niệm PHP, Composer và Markdown.

Các bước cài đặt Sculpin ​

Dưới đây là các bước chi tiết để cài đặt và cấu hình Sculpin trên ServBay:

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

Trước tiên, hãy tạo một thư mục dự án mới trong thư mục gốc của website ServBay (/Applications/ServBay/www). Ở đây, chúng ta sẽ đặt tên ví dụ là servbay-sculpin-app.

Mở Terminal và nhập các lệnh sau:

bash
cd /Applications/ServBay/www
mkdir servbay-sculpin-app
cd servbay-sculpin-app

Thư mục này sẽ chứa toàn bộ file dự án Sculpin của bạn.

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

ServBay đã tích hợp Composer sẵn, bạn không cần cài thêm gì cả. Bạn có thể sử dụng trực tiếp lệnh composer trong Terminal.

Ta sẽ dùng dự án khung blog Sculpin chính thức để khởi tạo nhanh. Tại thư mục servbay-sculpin-app bạn vừa tạo, chạy lệnh sau:

bash
composer create-project sculpin/sculpin-blog-skeleton .

Lệnh này sẽ tải về mã nguồn dự án blog Sculpin cùng toàn bộ dependencies và cài đặt vào thư mục hiện tại (.).

Bước 3: Cấu hình website trên ServBay ​

Để truy cập website Sculpin qua máy chủ web (Caddy hoặc Nginx) của ServBay, bạn cần thêm một cấu hình website trên ServBay.

  1. Mở ứng dụng ServBay: Khởi chạy giao diện đồ họa của ServBay.
  2. Chuyển tới tab "Website": Click vào tab "Website" trên thanh điều hướng.
  3. Thêm mới website: Ấn nút "+" ở góc dưới bên trái để thêm cấu hình website mới.
  4. Điền thông tin website:
    • Tên (Name): Đặt một tên dễ nhớ, ví dụ My Sculpin Site.
    • Tên miền (Domain): Nhập tên miền bạn muốn dùng cho site local, ví dụ servbay-sculpin.local. ServBay sẽ tự động cấu hình file hosts và SSL (bằng ServBay User CA) cho domain .local.
    • Loại website (Type): Chọn PHP, vì đây là ứng dụng PHP.
    • Phiên bản PHP (PHP Version): Chọn phiên bản PHP phù hợp với Sculpin. ServBay hỗ trợ nhiều phiên bản PHP, thường phiên bản mới là ổn.
    • Thư mục gốc website (Document Root): Đây là bước quan trọng nhất. Sculpin tạo ra file tĩnh tại thư mục output_dev (phát triển) hoặc output_prod (sản xuất) trong dự án. Đối với phát triển local, hãy trỏ thư mục gốc về: /Applications/ServBay/www/servbay-sculpin-app/output_dev
  5. Lưu lại cấu hình: Sau khi nhập xong, nhấn nút "Lưu". ServBay sẽ tự động áp dụng cấu hình lên máy chủ web (Caddy hoặc Nginx), thường không cần khởi động lại dịch vụ.

Bước 4: Build website Sculpin ​

Sau khi cấu hình website trong ServBay, bạn cần để Sculpin tạo ra các file tĩnh cho website.

Tại Terminal, kiểm tra bạn vẫn đang ở thư mục dự án /Applications/ServBay/www/servbay-sculpin-app, sau đó chạy lệnh cài đặt dependencies (nếu đã thực hiện ở bước 2 thì có thể bỏ qua, nhưng chạy lại cũng không sao):

bash
composer install

Tiếp theo, chạy lệnh generate của Sculpin để build website:

bash
vendor/bin/sculpin generate --watch
  • vendor/bin/sculpin: Đường dẫn file thực thi Sculpin do Composer cài đặt.
  • generate: Lệnh để Sculpin tạo website tĩnh, đọc nội dung từ thư mục source và xuất ra thư mục output (mặc định là output_dev).
  • --watch: Chế độ này giúp Sculpin tự động theo dõi các thay đổi trong thư mục source, mỗi khi có chỉnh sửa sẽ tự động build lại trang web, rất tiện lợi khi phát triển.

Khi lệnh chạy xong và hiện "Sculpin has generated your site!" hoặc thông báo tương tự, các file tĩnh đã được sinh ra trong thư mục output_dev.

Bước 5: Truy cập website local ​

Bây giờ, hãy mở trình duyệt web và truy cập tên miền bạn đã cấu hình ở bước 3:

https://servbay-sculpin.local

Do bạn đã trỏ thư mục gốc website về output_dev và lệnh sculpin generate --watch đang chạy, mọi thay đổi bạn thực hiện với nội dung hoặc template sẽ được cập nhật ngay lập tức tại địa chỉ trên. ServBay sẽ cấp SSL tự động giúp bạn luôn truy cập bằng HTTPS an toàn.

Phát triển với Sculpin ​

Bạn đã cài đặt và cấu hình thành công Sculpin trên ServBay, giờ có thể bắt đầu xây dựng website tĩnh của mình. Dưới đây là một số thao tác phát triển cơ bản:

Tổng quan cấu trúc dự án Sculpin ​

Hiểu về các thành phần chính trong dự án sẽ giúp bạn làm việc hiệu quả hơn:

servbay-sculpin-app/
├── app/                # Cấu hình ứng dụng, cache
├── output_dev/         # Thư mục xuất file tĩnh môi trường phát triển (ServBay sẽ trỏ vào đây)
├── output_prod/        # Thư mục xuất file tĩnh môi trường production
├── source/             # Mã nguồn website (nội dung Markdown, template Twig, tài nguyên tĩnh)
│   ├── _layouts/       # Template layout Twig
│   ├── _posts/         # File Markdown bài blog
│   ├── assets/         # Tài nguyên tĩnh (CSS, JS, hình ảnh, ...)
│   └── index.md        # File Markdown của trang chủ
├── vendor/             # Thư viện do Composer quản lý
├── sculpin.yml         # File cấu hình chính của Sculpin
├── composer.json       # File cấu hình dependencies Composer
└── ...các file khác

Phần lớn công việc của bạn sẽ thực hiện bên trong thư mục source.

Tạo bài blog mới ​

Để đăng một bài viết mới, chỉ cần tạo file Markdown trong thư mục source/_posts, đặt tên theo định dạng YYYY-MM-DD-slug.md.

Ví dụ tạo bài 2024-06-06-my-first-post.md:

markdown
---
title: "Bài viết đầu tiên"
date: 2024-06-06
tags: [Hướng dẫn, Sculpin, ServBay]
---

# Bài viết đầu tiên

Đây là nội dung bài blog Sculpin đầu tiên của tôi. Tôi sẽ chia sẻ trải nghiệm sử dụng ServBay và Sculpin tại đây.

Bạn có thể sử dụng cú pháp Markdown để soạn nội dung.

## Tiêu đề phụ

Danh sách:
- Mục 1
- Mục 2

Sau khi lưu file, do lệnh sculpin generate --watch đang chạy, Sculpin sẽ phát hiện và tự động sinh lại website. Bạn chỉ cần refresh trình duyệt ở https://servbay-sculpin.local để xem bài viết mới.

Tạo trang riêng lẻ ​

Để thêm một trang riêng biệt (ví dụ "Giới thiệu"), tạo file Markdown trực tiếp trong thư mục source, ví dụ about.md:

markdown
---
title: "Giới thiệu"
layout: page.html.twig # Chỉ định file layout sử dụng
---

# Hướng dẫn Sculpin với ServBay

Trang này hướng dẫn cách xây dựng website tĩnh với Sculpin và ServBay.

Sau khi lưu, Sculpin sẽ sinh file output_dev/about/index.html (nếu cấu hình pretty URL). Bạn có thể truy cập trang tại https://servbay-sculpin.local/about/.

Tùy chỉnh CSS, JS ​

Tài nguyên tĩnh (CSS, JS) thường nằm tại source/assets. Chỉnh sửa file như source/assets/css/style.css để thay đổi giao diện.

Các file này sẽ được copy vào thư mục output khi build. Sculpin với chế độ --watch cũng sẽ tự động tái tạo website khi có thay đổi.

Build website cho production ​

Khi hoàn thành website, bạn cần build phiên bản tối ưu cho production. Phiên bản này thường được nén tài nguyên, sẵn sàng cho triển khai.

Chạy lệnh sau để build bản production:

bash
vendor/bin/sculpin generate --env=prod

Kết quả sẽ nằm trong thư mục output_prod. Bạn chỉ việc upload toàn bộ file từ thư mục này lên các dịch vụ hosting tĩnh (GitHub Pages, Netlify, Vercel, hoặc chính server riêng...)

Nếu muốn xem bản production trên local, chỉ cần đổi thư mục gốc website trong cấu hình ServBay thành /Applications/ServBay/www/servbay-sculpin-app/output_prod, sau đó lưu lại và truy cập domain.

Lưu ý quan trọng ​

  • Đảm bảo ServBay đang chạy, website đã được kích hoạt.
  • Kiểm tra lệnh sculpin generate --watch vẫn đang hoạt động trong Terminal để auto build khi phát triển.
  • Đảm bảo thư mục gốc website trong ServBay trỏ đúng vào thư mục xuất file của Sculpin (thường là output_dev khi phát triển).
  • ServBay tự động cấp phát SSL cho domain .local, nhưng hệ điều hành có thể sẽ cần bạn tin tưởng vào ServBay User CA. Vui lòng tham khảo tài liệu ServBay để biết chi tiết.

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

Q: Tôi đã sửa file nhưng website không cập nhật?

A: Hãy kiểm tra bạn đã chạy lệnh vendor/bin/sculpin generate --watch trong thư mục dự án và tiến trình này không bị lỗi. Để ý Terminal có thông báo lỗi nào không. Ngoài ra, thử xóa cache trình duyệt hoặc dùng chế độ ẩn danh.

Q: Truy cập https://servbay-sculpin.local bị báo lỗi SSL?

A: Đây là chứng chỉ tự ký do ServBay sinh ra cho domain .local. Bạn cần cài đặt và tin tưởng root CA của ServBay theo hướng dẫn trong tài liệu sử dụng của ServBay.

Q: Làm sao để đổi phiên bản PHP?

A: Vào tab "Phần mềm" trong ServBay để cài đặt và quản lý các phiên bản PHP khác nhau. Vào lại tab "Website" để chọn và gán phiên bản PHP mong muốn cho website Sculpin rồi lưu lại.

Q: Sculpin hỗ trợ những template hay ngôn ngữ đánh dấu nào?

A: Sculpin mặc định dùng Twig cho template và hỗ trợ soạn nội dung bằng Markdown.

Tổng kết ​

Nhờ môi trường tích hợp của ServBay, việc cài đặt, cấu hình Sculpin trên macOS trở nên vô cùng đơn giản. ServBay cung cấp sẵn PHP, Composer, máy chủ web dễ cấu hình và SSL tự động – tạo nền tảng vững chắc cho phát triển Sculpin local. Làm theo hướng dẫn này, bạn sẽ nhanh chóng khởi tạo môi trường Sculpin và xây dựng, xem trước website tĩnh hiệu quả. Kết hợp sức mạnh của Sculpin với sự tiện lợi của ServBay, bạn sẽ tiết kiệm thời gian thiết lập, tập trung sáng tạo nội dung chất lượng thay vì loay hoay cấu hình local.