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

Tổng Quan

Craft CMS là hệ quản trị nội dung (CMS) mạnh mẽ, được các lập trình viên ưa chuộng nhờ khả năng mô hình hóa nội dung linh hoạt, giao diện thân thiện và các tính năng tối ưu cho phát triển. Đây là lựa chọn lý tưởng để xây dựng các website phức tạp và tùy biến cao.

Sử dụng ServBay làm môi trường phát triển Craft CMS mang lại nhiều lợi ích: được tích hợp sẵn PHP, cơ sở dữ liệu (MySQL hoặc PostgreSQL), máy chủ web (Caddy hoặc Nginx) cùng Composer và công cụ dòng lệnh. Điều này giúp đơn giản hóa quy trình cài đặt và cấu hình đáng kể.

Hướng dẫn này sẽ giúp bạn từng bước cài đặt và cấu hình dự án Craft CMS trong môi trường ServBay.

Điều Kiện Tiên Quyết

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

1. Đã cài đặt và chạy ServBay: Bạn cần cài đặt thành công ServBay trên macOS, đã khởi động đúng phiên bản PHP (hãy kiểm tra tài liệu chính thức Craft CMS để biết Craft CMS hỗ trợ bản PHP nào) cũng như các gói cơ sở dữ liệu cần thiết (thường là MySQL hoặc PostgreSQL). ServBay hỗ trợ nhiều phiên bản PHP & database, bạn có thể dễ dàng chuyển đổi và cấu hình theo yêu cầu.
2. Có kiến thức cơ bản về dòng lệnh: Bạn sẽ cần sử dụng Terminal để chạy lệnh, tạo thư mục hoặc thao tác với Composer.
3. Hiểu Composer: Craft CMS sử dụng Composer để quản lý thư viện. ServBay đã tích hợp Composer, bạn chỉ cần biết cách chạy lệnh composer create-project.

Các bước cài đặt Craft CMS

Dưới đây là các bước cài đặt và cấu hình Craft CMS trong môi trường ServBay.

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

Đầu tiên, hãy tạo một thư mục mới trong thư mục website mặc định của ServBay là /Applications/ServBay/www. ServBay thiết lập đây làm thư mục gốc cho máy chủ web để bạn dễ dàng truy cập dự án.

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

cd /Applications/ServBay/www
mkdir servbay-craft-app
cd servbay-craft-app

Lệnh này sẽ tạo một thư mục mới tên là servbay-craft-app trong /Applications/ServBay/www và chuyển vào đó.

Bước 2: Dùng Composer tạo dự án Craft CMS

ServBay đã tích hợp Composer, do đó bạn chỉ cần chạy Composer trong thư mục dự án để khởi tạo dự án Craft CMS. Craft CMS khuyến nghị cài đặt qua Composer.

Trong thư mục servbay-craft-app, nhập lệnh:

composer create-project craftcms/craft .

Lệnh này sẽ tải về phiên bản mới nhất của Craft CMS cùng toàn bộ thư viện phụ thuộc vào thư mục hiện tại (.). Vui lòng đợi Composer hoàn tất quy trình này.

Bước 3: Tạo cơ sở dữ liệu và người dùng

Craft CMS cần một cơ sở dữ liệu để lưu trữ dữ liệu và cấu hình. Ta sẽ dùng công cụ phpMyAdmin hoặc Adminer được cài sẵn trên ServBay. Dưới đây lấy phpMyAdmin làm ví dụ.

1. Truy cập công cụ quản trị cơ sở dữ liệu (phpMyAdmin) của ServBay

   Mở trình duyệt, truy cập panel phát triển địa phương của ServBay tại https://servbay.host/. Từ giao diện, nhấn vào liên kết "phpMyAdmin" để mở trình quản trị database.

   Lưu ý: Tài khoản truy cập mặc định thường là root, mật khẩu ServBay.dev. Vì lý do bảo mật, nên thay đổi mật khẩu root hoặc tạo tài khoản người quản trị riêng ngay sau khi đăng nhập.

2. Tạo tài khoản người dùng database

   Dù bạn có thể dùng tài khoản root kết nối Craft CMS, nhưng tốt nhất nên tạo người dùng riêng biệt cho từng ứng dụng để tăng bảo mật.

   1. Truy cập trang quản lý tài khoản người dùng

      Tại giao diện chính phpMyAdmin, chọn menu trên cùng "Tài khoản người dùng".

   2. Thêm tài khoản người dùng mới

      Chọn "Thêm tài khoản người dùng". Nhập các thông tin sau:

      • Tên người dùng: Ví dụ craft_user.
      • Máy chủ: Chọn localhost (chỉ kết nối từ máy cục bộ).
      • Mật khẩu: Đặt mật khẩu an toàn (tránh dùng ví dụ như password123, đặc biệt với môi trường thật. Có thể dùng mật khẩu đơn giản để thử nghiệm cục bộ nhưng vẫn nên chú ý bảo mật).
      • Nhập lại mật khẩu: Xác nhận lại mật khẩu.
      • Trong phần "Tạo cơ sở dữ liệu trùng tên và cấp mọi quyền", chọn tùy chọn này. Như vậy hệ thống sẽ tự tạo database tên craft_user với người dùng cùng tên, đồng thời cấp toàn bộ quyền.
      • Đảm bảo tích vào ô "Cấp mọi quyền".
      • Nhấn nút "Thực hiện" ở cuối trang.

   Như vậy bạn đã có một tài khoản database craft_user và một cơ sở dữ liệu cùng tên với đầy đủ quyền truy cập.

Bước 4: Cấu hình máy chủ web (Tạo website mới trong ServBay)

Để máy chủ web (Caddy hoặc Nginx) trong ServBay phục vụ dự án Craft CMS, bạn cần thêm một "Website" mới bằng tính năng quản lý trong ServBay.

1. Mở ứng dụng ServBay

   Khởi động ứng dụng ServBay trên máy.

2. Thêm website mới

   Trên panel điều hướng bên trái, bấm vào mục "Website" (phiên bản cũ có thể là “Host”). Nhấn dấu "+" hoặc nút "Thêm Website" để cài đặt website mới.

   Nhập các thông tin sau:

   • Tên (Name): Đặt tên dễ nhớ, ví dụ My Craft Site.
   • Tên miền (Domains): Nhập tên miền dùng để truy cập cục bộ, ví dụ servbay-craft.local. ServBay sẽ tự cấu hình DNS nội bộ, nên bạn có thể dùng domain này truy cập website.
   • Loại website (Type): Chọn PHP.
   • Phiên bản PHP (PHP Version): Chọn đúng phiên bản PHP phù hợp với Craft CMS (đã kiểm tra ở phần điều kiện tiên quyết). ServBay hỗ trợ đa phiên bản PHP song song.
   • Thư mục gốc website (Website Root): Bước này rất quan trọng! File truy cập của Craft CMS (ví dụ index.php) nằm trong thư mục web bên trong thư mục dự án. Về bảo mật, root máy chủ web phải chỉ vào thư mục web, không phải toàn bộ dự án. Nhập: /Applications/ServBay/www/servbay-craft-app/web Đảm bảo đường dẫn chính xác, trỏ tới thư mục web bên trong thư mục dự án bạn đã tạo.

3. Lưu cấu hình

   Sau khi hoàn tất, bấm "Lưu". ServBay sẽ tự động reload cấu hình web server để website mới có hiệu lực. Bạn sẽ thấy website servbay-craft.local xuất hiện trong danh sách site của ServBay.

Bước 5: Chạy trình cài đặt Craft CMS

Giờ bạn có thể truy cập website qua tên miền đã cấu hình để chạy trình cài đặt Craft CMS.

1. Truy cập trang cài đặt

   Mở trình duyệt và truy cập https://servbay-craft.local/. Craft CMS sẽ nhận ra hệ thống chưa cài đặt và tự động chuyển đến trang cài đặt, thường là https://servbay-craft.local/index.php?p=admin/install.

2. Nhập thông tin kết nối database

   Ở bước cấu hình database, nhập thông tin đã tạo ở bước 3:

   • Máy chủ cơ sở dữ liệu (Database Server): localhost
   • Tên cơ sở dữ liệu (Database Name): craft_user (hoặc tên database bạn tạo)
   • Tên người dùng (Username): craft_user (hoặc tên user bạn đã chọn)
   • Mật khẩu (Password): Là mật khẩu bạn đã đặt khi tạo tài khoản.

   Nhấn tiếp tục. Craft CMS sẽ thử kết nối database. Nếu thành công, chuyển sang bước kế tiếp.

3. Tạo tài khoản quản trị

   Làm theo hướng dẫn trên màn hình để tạo tài khoản quản trị viên. Nhập tên người dùng, mật khẩu và email quản trị. Ưu tiên mật khẩu mạnh.

   Nhấn tiếp tục.

4. Cấu hình site

   Nhập tên website và các thông tin cơ bản khác.

   Nhấn nút "Hoàn tất cài đặt (Finish Up)". Craft CMS sẽ hoàn thành các bước cuối cùng như tạo bảng dữ liệu và file cấu hình.

   Sau khi hoàn thành, bạn sẽ được chuyển đến trang đăng nhập quản trị Craft CMS.

Bước 6: Cấu hình ban đầu & khám phá Craft CMS

Đăng nhập vào trang quản trị Craft CMS để thực hiện một số thiết lập ban đầu:

1. Kiểm tra file .env: Craft CMS dùng file .env để quản lý biến môi trường (bao gồm thông tin kết nối database). File này tự động sinh khi cài đặt và bạn có thể tìm thấy tại thư mục gốc dự án (servbay-craft-app/). Có thể chỉnh sửa file này để cài đặt thêm, ví dụ đặt biến CRAFT_ENVIRONMENT là dev.
2. Cài plugin: Trong trang quản trị, vào "Plugins" để duyệt, cài đặt hoặc quản lý các plugin Craft CMS nhằm mở rộng chức năng.
3. Tạo cấu trúc nội dung: Truy cập mục "Cài đặt (Settings)" để định nghĩa các trường, mục, phân loại, thẻ... cho cấu trúc nội dung của bạn.
4. Cấu hình gửi email: Nếu cần thử gửi mail ở môi trường cục bộ, có thể cấu hình Craft CMS dùng Mailpit hoặc Mailhog (được tích hợp trong ServBay). Cấu hình giao thức gửi mail SMTP, server là localhost, port lấy theo cổng SMTP do Mailpit/Mailhog cung cấp (hiển thị trên giao diện ServBay).

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

• Hỏi: Nếu gặp lỗi không kết nối được database khi cài đặt Craft CMS phải làm sao?
  • Đáp: Kiểm tra lại địa chỉ máy chủ (localhost), tên database, tên người dùng, mật khẩu nhập trong trình cài đặt Craft CMS có đúng với thông tin đã tạo trên phpMyAdmin chưa. Đảm bảo dịch vụ database (MySQL hoặc PostgreSQL) của ServBay đang hoạt động.
• Hỏi: Truy cập servbay-craft.local bị 404 hoặc trang trắng?
  • Đáp:
    • Kiểm tra xem lúc tạo website trong ServBay, "Thư mục gốc website" đã chính xác là /Applications/ServBay/www/servbay-craft-app/web chưa. Đây là lý do hay gặp nhất.
    • Đảm bảo web server (Caddy hoặc Nginx) và PHP trong ServBay đã khởi động.
    • Kiểm tra website servbay-craft.local đã được kích hoạt trong danh sách website của ServBay chưa.
• Hỏi: Cài đặt Craft CMS bằng Composer rất chậm hoặc thất bại?
  • Đáp: Có thể do vấn đề kết nối mạng hoặc nguồn mirrors của Composer. Bạn hãy thử chuyển composer sang mirror trong nước như Aliyun hoặc Packagist China.
• Hỏi: Sau khi cài đặt, trang quản trị hoặc frontend bị lỗi giao diện, hình ảnh không hiển thị?
  • Đáp: Thông thường là do phân quyền file. Đảm bảo người dùng của ServBay có đầy đủ quyền ghi vào các thư mục như storage, web/cpresources... ServBay thường tự xử lý quyền nhưng nếu gặp lỗi hãy kiểm tra hoặc reset lại permission cho các thư mục này.

Tổng Kết

Chỉ với các bước trên, bạn đã có thể cài đặt và cấu hình thành công Craft CMS trên môi trường phát triển cục bộ ServBay. ServBay giúp đơn giản hóa toàn bộ quy trình quản lý phiên bản PHP, thiết lập database và cấu hình web server, để bạn tập trung phát triển ứng dụng với Craft CMS. Giờ đây, hãy bắt đầu tận dụng những tính năng vượt trội về mô hình hóa nội dung mà Craft CMS mang lại để xây dựng website hoặc ứng dụng của bạn!