Cài Đặt và Cấu Hình OctoberCMS Trên Môi Trường ServBay

Tổng Quan

OctoberCMS là một hệ quản trị nội dung (CMS) mã nguồn mở xây dựng trên nền tảng Laravel mạnh mẽ, được yêu thích nhờ sự đơn giản, linh hoạt và thân thiện với lập trình viên. Tài liệu này sẽ hướng dẫn bạn cách cài đặt và cấu hình thành công OctoberCMS trong ServBay — môi trường phát triển web cục bộ tất cả trong một dành cho macOS — để bạn có thể nhanh chóng bắt đầu phát triển dự án sử dụng OctoberCMS.

OctoberCMS Là Gì?

OctoberCMS cung cấp giao diện quản trị trực quan cùng khả năng phát triển frontend mạnh mẽ, cho phép nhà phát triển sử dụng các khái niệm quen thuộc của Laravel (như Eloquent ORM, hệ thống template Blade, v.v.) để xây dựng mọi loại website, từ blog đơn giản đến ứng dụng doanh nghiệp phức tạp.

Yêu Cầu Chuẩn Bị

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

1. ServBay đã được cài đặt và đang chạy trên hệ thống macOS của bạn.
2. Gói PHP (khuyến nghị 7.4 trở lên) và MySQL/MariaDB đã được kích hoạt, vận hành trên ServBay.
3. Gói Composer đã được bật trong ServBay.
4. Có kiến thức cơ bản về thao tác dòng lệnh.

Các Bước Cài Đặt OctoberCMS

Dưới đây là các bước chi tiết để cài đặt và cấu hình OctoberCMS trong môi trường ServBay:

Bước 1: Tạo Thư Mục Dự Án

Đầu tiên, điều hướng đến thư mục gốc web được ServBay đề xuất /Applications/ServBay/www và tạo một thư mục mới cho dự án OctoberCMS của bạn.

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

Bước 2: Cài Đặt OctoberCMS Bằng Composer

ServBay đã tích hợp sẵn Composer và cấu hình hoàn chỉnh. Hãy đảm bảo bạn đã bật gói Composer trong bảng điều khiển ServBay. Sau đó, chạy lệnh Composer dưới đây tại thư mục dự án mới tạo để tải và cài đặt các tập tin lõi của OctoberCMS:

composer create-project october/october .

Lệnh này sẽ tải phiên bản mới nhất của OctoberCMS từ kho chính thức vào thư mục hiện tại (.).

Bước 3: Tạo Cơ Sở Dữ Liệu Và Người Dùng

OctoberCMS cần một cơ sở dữ liệu để lưu trữ nội dung, tài khoản và các cấu hình. Chúng ta sẽ sử dụng công cụ quản trị cơ sở dữ liệu phpMyAdmin tích hợp sẵn của ServBay để tạo database và user tương ứng.

1. Truy cập công cụ phpMyAdmin của ServBay

   Mở trình duyệt và vào bảng điều khiển phát triển cục bộ ServBay tại https://servbay.host/. Tìm hoặc truy cập liên kết phpMyAdmin, thường là https://servbay.host/phpmyadmin/, để vào công cụ quản lý database.

2. Tạo người dùng cơ sở dữ liệu

   Để đảm bảo an toàn và tách biệt, nên tạo một user và database độc lập cho mỗi ứng dụng.

   1. Chuyển đến trang quản lý tài khoản người dùng

      Trên trang chính của phpMyAdmin, nhấp vào "Người dùng".

   2. Thêm người dùng mới

      Nhấp vào "Thêm tài khoản người dùng". Điền các thông tin sau:

      • Tên người dùng: Nhập tên cho user kết nối OctoberCMS, ví dụ october_user.
      • Máy chủ: Chọn localhost hoặc 127.0.0.1 để giới hạn quyền truy cập chỉ từ local, tăng bảo mật.
      • Mật khẩu: Nhập một mật khẩu an toàn, duy nhất. Không dùng ví dụ mật khẩu password123 trên môi trường thật!
      • Nhập lại mật khẩu: Xác nhận mật khẩu vừa nhập.
      • Tại phần "Cơ sở dữ liệu cho user này", chọn "Tạo database cùng tên với user và cấp toàn bộ quyền truy cập". Điều này sẽ tự động tạo cơ sở dữ liệu mang tên october_user và cấp quyền đầy đủ cho user này.
      • Đảm bảo đã chọn "Cấp toàn quyền toàn cục" ở phần quyền hạn (nếu đã chọn tạo database cùng tên ở bước trước, mục này thường được tự động hoàn thiện).
      • Nhấn nút "Thực hiện" ở cuối trang để hoàn tất việc tạo người dùng và cơ sở dữ liệu.

Bước 4: Cấu Hình Máy Chủ Web (Thêm Trang Web Trong ServBay)

Để có thể truy cập ứng dụng OctoberCMS qua trình duyệt, bạn cần cấu hình một website cục bộ trong ServBay.

1. Thêm trang web mới

   Mở bảng điều khiển ServBay, chọn mục "Trang web" ở thanh bên trái (lưu ý: bản cũ có thể ghi "Host"). Nhấn nút "Thêm trang web".

   Điền các nội dung sau:

   • Tên: Đặt tên dễ nhận biết, ví dụ My OctoberCMS Site.
   • Tên miền: Nhập tên miền bạn muốn dùng để truy cập cục bộ, ví dụ servbay-octobercms.local. Nên sử dụng hậu tố .local để tránh trùng với tên miền thật.
   • Loại website: Chọn PHP.
   • Phiên bản PHP: Chọn phiên bản PHP bạn muốn sử dụng, đảm bảo phù hợp (bật sẵn và đáp ứng yêu cầu OctoberCMS).
   • Thư mục gốc website: Nhấp vào nút chọn thư mục, trỏ tới thư mục dự án vừa tạo ở bước 1 /Applications/ServBay/www/servbay-octobercms-app.

2. Lưu cấu hình và khởi động lại ServBay

   Sau khi hoàn tất cấu hình, nhấn nút lưu. ServBay sẽ nhắc bạn áp dụng thay đổi — thường cần khởi động lại các gói liên quan (như Caddy hoặc Nginx) cũng như bản thân ServBay. Hãy làm theo hướng dẫn, đảm bảo thay đổi đã được áp dụng. ServBay sẽ tự động ánh xạ tên miền servbay-octobercms.local tới localhost (127.0.0.1).

Bước 5: Cấu Hình Biến Môi Trường Cho OctoberCMS

OctoberCMS (trên nền tảng Laravel) sử dụng file .env để quản lý biến môi trường như thông tin database, secret key, v.v.

1. Sao chép file cấu hình môi trường mẫu

   Ở thư mục gốc dự án OctoberCMS (/Applications/ServBay/www/servbay-octobercms-app), sao chép file .env.example và đổi tên thành .env:

   cd /Applications/ServBay/www/servbay-octobercms-app
   cp .env.example .env

2. Chỉnh sửa file .env

   Mở file .env vừa tạo bằng trình soạn thảo bạn ưa thích. Tìm đến phần cấu hình database và cập nhật theo thông tin bạn đã tạo ở bước 3:

   # ... các dòng cấu hình khác ...
   
   DB_CONNECTION=mysql
   DB_HOST=127.0.0.1
   DB_PORT=3306
   DB_DATABASE=october_user  # Thay thế bằng tên database bạn đã tạo
   DB_USERNAME=october_user  # Thay thế bằng tên user database bạn đã tạo
   DB_PASSWORD=password123   # Thay bằng mật khẩu thực tế bạn đã đặt
   
   # ... các dòng cấu hình khác ...

   Lưu ý quan trọng: Hãy đảm bảo cập nhật chính xác các giá trị DB_DATABASE, DB_USERNAME, và DB_PASSWORD theo thông tin bạn vừa thiết lập ở bước 3.

Bước 6: Chạy Trình Cài Đặt OctoberCMS

OctoberCMS cung cấp trình cài đặt dựa trên web để hoàn tất các thiết lập như migrate database, tạo tài khoản quản trị viên, v.v.

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

   Mở trình duyệt và truy cập tên miền bạn đã cấu hình ở bước 4 kèm đuôi /install.php, ví dụ:

   https://servbay-octobercms.local/install.php

   Bạn sẽ thấy trang hướng dẫn cài đặt từng bước của OctoberCMS.

2. Nhập thông tin cơ sở dữ liệu

   Trình hướng dẫn sẽ yêu cầu bạn nhập thông tin kết nối database. Hãy điền giống hệt các thông tin bạn đã cấu hình trong file .env:

   • Loại database: MySQL
   • Host database: localhost hoặc 127.0.0.1
   • Tên database: october_user
   • Tên user database: october_user
   • Mật khẩu database: password123

   (Xin nhắc lại: hãy dùng chính xác mật khẩu thực tế bạn đã đặt)

3. Nhập thông tin quản trị viên

   Làm theo chỉ dẫn trên màn hình để điền các thông tin tài khoản quản trị: Username, mật khẩu, email đăng nhập, v.v.

4. Hoàn Thành Cài Đặt

   Nhấn vào nút "Cài đặt" hoặc tương ứng trên giao diện hướng dẫn. Hệ thống sẽ tự động migrate database, sinh khóa bảo mật và hoàn tất cài đặt. Hãy chờ quá trình này hoàn thành.

Bước 7: Cài Đặt Plugin Và Giao Diện (Tùy Chọn)

Sau khi cài đặt xong, bạn có thể đăng nhập vào khu vực quản trị của OctoberCMS tại https://servbay-octobercms.local/backend.

1. Cài đặt plugin

   Trong admin, chuyển đến mục "Hệ thống" -> "Cập nhật" -> "Plugin". Tại đây bạn có thể tìm kiếm, cài các plugin đa dạng từ Marketplace để mở rộng chức năng.

2. Cài đặt giao diện

   Chuyển đến "Hệ thống" -> "Cập nhật" -> "Giao diện". Bạn có thể duyệt, cài giao diện phù hợp nhu cầu dự án của mình.

Cấu Hình Và Sử Dụng Cơ Bản Sau Cài Đặt

Sau khi cài đặt OctoberCMS thành công, bạn có thể bắt đầu phát triển website ngay. Một số thao tác ban đầu thông dụng bao gồm:

• Truy cập trang chủ: Vào tên miền cục bộ của bạn https://servbay-octobercms.local/ để xem website (sử dụng theme mặc định).
• Truy cập admin: Vào https://servbay-octobercms.local/backend, dùng tài khoản admin vừa tạo để đăng nhập.
• Tạo trang: Trong admin, chuyển đến "CMS" -> "Trang" để tạo/biên tập trang website.
• Tạo block nội dung: Trong admin, chọn "CMS" -> "Nội dung" để tạo các đoạn nội dung có thể tái sử dụng.
• Cấu hình giao diện: Dưới "CMS" -> "Giao diện" để tinh chỉnh các thiết lập, bố cục của giao diện hiện tại.
• Quản lý user và phân quyền: Vào "Hệ thống" -> "Quản trị" để quản lý user backend và phân quyền.

Những Câu Hỏi Thường Gặp (FAQ)

• Hỏi: Truy cập servbay-octobercms.local chỉ thấy trang mặc định của ServBay hoặc gặp lỗi?
  • Đáp: Kiểm tra kỹ trên bảng điều khiển ServBay xem bạn đã thêm website servbay-octobercms.local chưa, và thư mục gốc có đúng là /Applications/ServBay/www/servbay-octobercms-app không. Sau khi cấu hình hoặc chỉnh sửa, nhớ áp dụng thay đổi và khởi động lại các dịch vụ liên quan. Kiểm tra trạng thái vận hành của ServBay, đảm bảo Caddy/Nginx và PHP đang chạy.
• Hỏi: Truy cập https://servbay-octobercms.local/install.php bị trắng trang hoặc báo lỗi?
  • Đáp: Đa phần do lỗi PHP. Xem log lỗi PHP trong bảng điều khiển ServBay để xác định cụ thể. Nguyên nhân phổ biến: quyền truy cập tập tin (đảm bảo thư mục storage, themes, plugins và các thư mục con có quyền ghi cho user web server), phiên bản PHP không tương thích, thiếu extension cần thiết, v.v.
• Hỏi: Bị lỗi kết nối tới database trong lúc cài đặt?
  • Đáp: Kiểm tra thật kỹ thông tin kết nối trong file .env (DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, DB_PASSWORD) phải hoàn toàn trùng khớp với thông tin bạn tạo trên phpMyAdmin. Đảm bảo MySQL/MariaDB trên ServBay đang chạy.
• Hỏi: Lệnh composer create-project chạy thất bại?
  • Đáp: Đảm bảo đã bật Composer và PHP đúng phiên bản trên ServBay. Kiểm tra kết nối mạng vì Composer cần tải file về.

Tổng Kết

Nhờ môi trường ServBay tiện lợi, bạn có thể dễ dàng và nhanh chóng cài đặt, cấu hình OctoberCMS trên macOS. Làm theo hướng dẫn này, bạn sẽ có một nền tảng phát triển cục bộ mạnh mẽ, thân thiện với developer cho dự án web tiếp theo. Giờ đây, hãy khám phá các tính năng mạnh mẽ của OctoberCMS và xây dựng những website ấn tượng!