Cài đặt phần mềm và kích hoạt license

Chuẩn bị trước khi cài

• Tên miền đã trỏ về hosting hoặc VPS và đã có SSL, tức trình duyệt hiện ổ khoá khi mở https://.
• PHP 8.3 trở lên, bật đủ 10 extension pdo_mysql, mbstring, openssl, fileinfo, zip, xmlreader, dom, iconv, ctype, tokenizer. Nên bật thêm intl và gd để in mã vạch và xếp tên tiếng Việt đúng.
• MySQL 8.0 trở lên hoặc MariaDB 10.6 trở lên, một database trống và một user có quyền "ALL PRIVILEGES" trên database đó.
• Khoảng 300 MB dung lượng cho mã nguồn và thư viện, cộng phần ảnh sản phẩm về sau.
• Máy chủ gọi ra ngoài được qua HTTPS tới license.levantoan.com để kích hoạt.
• File zip phần mềm, ví dụ banhang-20261102-2250.zip của bản 0.14.0, nặng khoảng 15 MB. Giữ nguyên file zip, không giải nén trên máy tính.
• Mã license DevVN gửi khi mua, dạng BH-XXXX-XXXX-XXXX-XXXX.

Chọn cách cài: hosting cPanel hay VPS

Hai cách cùng kết thúc ở trình cài trên trình duyệt. Khác nhau ở phần đưa mã nguồn lên máy chủ. Gói phần mềm có sẵn hai bản PDF hướng dẫn từng bước kèm ảnh: Huong-dan-cai-dat-Phan-mem-ban-hang-tren-cPanel.pdf và Huong-dan-cai-dat-Phan-mem-ban-hang-tren-VPS-Webinoly.pdf. Hai mục tóm tắt kế tiếp cho bạn biết trước khối lượng việc.

Tóm tắt trên hosting cPanel

1. Mở "Database Wizard", đặt tên database (cPanel tự thêm tên tài khoản phía trước, ví dụ tenhosting_banhang), tạo user bằng "Password Generator", tích "ALL PRIVILEGES". Ghi lại tên database, tên user và mật khẩu.
2. Mở "File Manager", vào thư mục của tên miền, bấm "Upload" chọn file zip. Chọn file zip, bấm "Extract" giải nén ngay tại thư mục đó, rồi xoá file zip.
3. Mở "MultiPHP Manager", tích tên miền, chọn "PHP 8.3", bấm "Apply". Làm việc này sau khi giải nén, kể cả khi bảng đã ghi PHP 8.3 từ trước.
4. Mở https:// tên miền của bạn. Phần mềm tự tạo file cấu hình rồi chuyển sang trình cài.

Bước 3 phải làm sau khi giải nén vì gói phần mềm có file .htaccess riêng. Giải nén đè lên làm mất dòng chọn PHP mà cPanel ghi vào file đó, tên miền quay về PHP mặc định của máy chủ và trang báo "Phần mềm cần PHP 8.3 trở lên".

Tóm tắt trên VPS Webinoly

1. Kiểm php -v ra 8.3 trở lên, đủ extension, mariadb --version ra 10.6 trở lên.
2. Tạo site kèm database: site ten-mien-cua-ban.vn -mysql, chép lại ba dòng "Database Name", "Database User", "Password". Bật SSL bằng site ten-mien-cua-ban.vn -ssl=on.
3. Upload zip qua SFTP, giải nén vào htdocs, chạy chown -R www-data:www-data ., đặt quyền 750 cho thư mục và 640 cho file.
4. Sửa file cấu hình Nginx của site: dòng root trỏ vào htdocs/public. Kiểm bằng nginx -t rồi nạp lại Nginx.
5. Chạy sudo -u www-data php artisan storage:link để ảnh sản phẩm hiện được (Webinoly chặn hàm tạo liên kết khi chạy trên web).
6. Mở https:// tên miền và chạy trình cài. Cài xong hạ quyền file .env xuống 640 và chạy sudo -u www-data php artisan optimize.

Mọi lệnh php artisan trên VPS chạy bằng sudo -u www-data. Chạy bằng root thì file cache, file log mới thuộc root, PHP-FPM không ghi được và trang báo lỗi 500.

Trình cài 4 bước trên trình duyệt

Lần đầu mở tên miền, phần mềm sinh file .env với khoá ứng dụng mới, đặt chế độ chạy thật và ghi địa chỉ đang mở vào APP_URL, rồi chuyển tới /install. Mở bằng https:// ngay từ lần này để phần mềm ghi đúng địa chỉ có SSL. Mỗi bước kiểm lại các bước trước, nên gõ thẳng địa chỉ bước sau sẽ bị đưa về bước còn thiếu kèm câu "Làm xong bước ... trước."

Bước 1: Kiểm tra máy chủ

Dòng nào báo "Thiếu" (màu đỏ) phải sửa trước khi đi tiếp: trên cPanel bật extension ở "Select PHP Version", trên VPS cài gói tương ứng, ví dụ apt install php8.4-intl. Sửa xong bấm Kiểm tra lại. Dòng "Nên bật" (màu vàng) không chặn cài đặt. Hết dòng đỏ thì bấm Tiếp tục.

Gặp trang "Cần cấp quyền ghi cho thư mục" ngay khi mở tên miền nghĩa là PHP không ghi được vào các thư mục ghi trên trang. Trên cPanel đặt quyền 755 cho từng thư mục đó trong File Manager; trên VPS giao lại thư mục cho www-data.

Bước 2: Database

Giữ Host là localhost và Cổng là 3306. Điền tên database, user và mật khẩu đã ghi lại, bấm Kiểm tra kết nối và lưu. Mật khẩu ở đây là mật khẩu của user database, không phải mật khẩu đăng nhập cPanel. Phần mềm không hiện lại mật khẩu, quay lại bước này thì gõ lại. Mỗi địa chỉ IP được thử 10 lần trong 10 phút; database đang có bảng của phần mềm khác thì bị từ chối.

Bước 3: Cài đặt

Bấm Cài đặt rồi chờ, đừng đóng trang. Phần mềm tạo bảng, thêm dữ liệu bắt buộc (5 hình thức thanh toán, các hình thức thu chi, 4 nhóm quyền mẫu) và tạo liên kết public/storage cho ảnh sản phẩm. Lần chạy thử với MySQL 8.0.35 mất khoảng 30 giây.

Ô Nạp dữ liệu mẫu để dùng thử mặc định không tích. Tích thì sau bước 4 phần mềm thêm 3 kho, khoảng 24 sản phẩm, khách, nhà cung cấp, đơn hàng, phiếu nhập và phiếu thu chi của 45 ngày gần đây. Dữ liệu mẫu không có nút xoá riêng, nên chỉ tích khi cài để xem thử. Bước này báo "Chưa tạo được liên kết ảnh" khi hosting chặn hàm tạo liên kết: cài đặt vẫn đi tiếp, chỉ ảnh sản phẩm chưa hiện (cách sửa ở bảng cuối bài).

Bước 4: Cửa hàng, tài khoản

Tên cửa hàng, điện thoại, địa chỉ in trên hoá đơn và sửa lại được ở Thông tin cửa hàng. Mã đăng nhập chỉ gồm chữ không dấu, số, dấu gạch dưới và gạch ngang. Mật khẩu tối thiểu 8 ký tự, ô Nhập lại mật khẩu phải khớp. Bấm Hoàn tất cài đặt: phần mềm tạo tài khoản chủ cửa hàng, tạo kho "Kho chính" và chuyển về trang đăng nhập.

Từ lúc này mọi địa chỉ /install trả 404, người khác không chạy lại trình cài được.

Kích hoạt license

Phần mềm chỉ dùng được sau khi kích hoạt license cho tên miền đang chạy. Đăng nhập bằng tài khoản chủ cửa hàng: mở trang nào phần mềm cũng chuyển sang Thiết lập, tab Cập nhật phần mềm. Nhân viên đăng nhập lúc này thấy trang "Phần mềm chưa kích hoạt" với dòng "Báo chủ cửa hàng đăng nhập để kích hoạt."

1. Tab Cập nhật phần mềm chỉ tài khoản chủ cửa hàng thấy.
2. Dòng vàng "Phần mềm chưa kích hoạt" còn hiện thì các trang khác chưa mở được.
3. Gõ mã DevVN gửi vào ô Mã license, dạng BH-XXXX-XXXX-XXXX-XXXX.
4. Bấm Lưu và kiểm tra. Phần mềm gọi máy chủ license.levantoan.com và gắn license với tên miền in đậm ngay dưới ô (lấy từ APP_URL, bỏ www.).
5. Khung trạng thái đổi từ "Chưa nhập mã license." sang "License hợp lệ cho ... Được cập nhật đến hết ngày ...", kèm dòng xanh "Đã kích hoạt cho" tên miền. Lúc này các trang khác mở được.
6. Khung Phiên bản ghi bản đang dùng. Có bản mới trong hạn cập nhật thì khung này hiện danh sách thay đổi và nút Cập nhật lên bản x.y.z.

License dùng vĩnh viễn trên tên miền đã kích hoạt và được nhận bản mới trong 1 năm kể từ ngày mua. Hết hạn cập nhật, phần mềm vẫn chạy đủ chức năng, chỉ không tải được bản phát hành sau ngày đó. Bấm cập nhật thì phần mềm bắt tích "Tôi đã sao lưu database" trước, tạm dừng khoảng 1 đến 2 phút và nhân viên thấy trang bảo trì trong lúc đó.

Phần mềm tự kiểm license mỗi tuần

Sau khi kích hoạt, phần mềm kiểm lại license mỗi tuần một lần. Lượt kiểm chạy sau khi trang đã hiện, người đang bán không phải chờ. Tab Cập nhật phần mềm ghi "Lần kiểm gần nhất" kèm nút Kiểm tra ngay để kiểm liền khi cần (nút chỉ hiện khi đã lưu mã).

Cron: 4 việc định kỳ

Bán hàng, nhập kho, báo cáo, in và gửi mail hoá đơn chạy ngay lúc bấm, không cần cron. Cron chạy bốn việc dưới đây; việc của tính năng chưa bật thì chạy mà không làm gì. Thêm cron ngay sau khi cài để sau này bật tính năng nào là tính năng đó chạy đủ.

• woo:sync mỗi 15 phút đồng bộ đơn và tồn kho với website WooCommerce, chỉ chạy khi đã tích "Tự đồng bộ mỗi 15 phút (cần cron trên hosting)" ở tab WooCommerce.
• einvoice:sync mỗi 15 phút hỏi M-Invoice trạng thái hoá đơn điện tử đang chờ, không tạo hoá đơn mới. Không có cron thì bấm "Cập nhật trạng thái" ở từng đơn.
• points:expire lúc 00:10 mỗi ngày ghi dòng "Hết hạn" vào lịch sử điểm. Không có cron thì số dư điểm vẫn đúng, dòng này được ghi khi mở tab điểm của khách.
• updates:check mỗi giờ: tới hạn thì kiểm license và bản mới, một tuần một lần. Không có cron thì lượt kiểm chạy khi có người đăng nhập mở trang.

Trên cPanel mở "Cron Jobs" (nhóm Advanced), ô "Common Settings" chọn "Once Per Minute(* * * * *)", ô "Command" dán dòng dưới. Thay ten-mien-cua-ban.vn bằng tên thư mục tên miền của bạn:

cd ~/ten-mien-cua-ban.vn && /opt/cpanel/ea-php83/root/usr/bin/php artisan schedule:run >> /dev/null 2>&1

Phải ghi đường dẫn PHP đầy đủ như trên. Cron chạy từ thư mục home, ở đó lệnh php là bản mặc định của máy chủ; trên hosting dùng viết tài liệu, bản đó là PHP 7.4 và phần mềm không chạy được. Hosting CloudLinux chọn PHP ở "Select PHP Version" thì đường dẫn là /opt/alt/php83/usr/bin/php.

Trên VPS Webinoly chạy crontab -e bằng root và thêm một dòng:

* * * * * /usr/sbin/runuser -u www-data -- /usr/bin/php /var/www/ten-mien-cua-ban.vn/htdocs/artisan schedule:run >> /dev/null 2>&1

Kiểm tra lại

1. Mở https://ten-mien-cua-ban.vn/install: phải báo 404.
2. Mở https://ten-mien-cua-ban.vn/.env: trình duyệt phải báo 403 hoặc 404. Trang hiện nội dung file nghĩa là máy chủ không đọc file .htaccess, liên hệ hỗ trợ ngay.
3. Tab Cập nhật phần mềm có dòng "Đã kích hoạt cho" kèm tên miền của bạn.
4. Trang Tổng quan mở được, ô Kho trên đầu trang là "Kho chính" do trình cài tạo.
5. Thư mục storage/logs trong thư mục phần mềm không có file log mới. Có file log là có lỗi thật cần xem.

Hay vướng

Cài và kích hoạt xong, điền tên, địa chỉ in trên hoá đơn và đặt tên kho ở bài Thông tin cửa hàng và kho.