Lunar Architecture

Project dùng cho việc provision nhanh chóng các store bán merch theo chủ đề. (Sản phẩm chủ yếu lấy từ Redbubble).

Domain chính tdalunar.com: dùng cho việc khỏi tạo các server hub, ví dụ: s1, s2, sx… Dev server dev.tdalunar.com: Server cho dev dùng test, cấu hình giống các server hub thực tế. HQ control hq.tdalunar.com: Nơi quản lý tập trung các chức năng chung cho hệ thống lunar.

Mô hình hệ thống

Từng server sẽ được setup 1 website chính, gọi là hub (central). Các hub sẽ tạo các website trên server. Quy tắc đặt tên s1.tdalunar.com, s2.tdalunar.com, …

Stack sử dụng

Stack:

Laravel
AlpineJS
Livewire
SQLite
File storage: Bunny
Queue: Redis + horizon

Server:

Caddy: cấu hình đơn giản, auto TLS thay vì Nginx và Certbot.
SQLite
PHP-FPM

Kiến trúc website sử dụng 2 package chính là

Lunarphp cho các function và backend liên quan đến ecommerce
TenancyForLaravel dùng cho kiến trúc multi tenancy, 1 server sẽ phục vụ nhiều website.

Các feature có thể viết như 1 app Laravel cơ bản, hoặc chia thành các package trong thư mục packages của dự án. Điều này giúp cho việc maintain code nhẹ nhàng hơn.

Toàn bộ các website sử dụng chung 1 Bunny storage, được chia thành các sub folder theo tên domain.

Lunar hub là gì?

Lunar hub các các website chính cài trên từng server, phụ trách cho việc khởi tạo các website trên server này.

Hub admin url: hubdomain/hub

Giao diện admin của hub có thể thực hiện các hành động sau:

Toggle chế độ maintenance của website
Download, upload (replace) database của 1 store (hỗ trợ cho việc việc chuyển store từ server này sang server khác)
Quản lý store

Tenant store là gì?

Tenant hay là các store bán sản phẩm, được tạo trên 1 hub.

Store admin url: `domain/lunar

Admin của store sử dụng cho việc quản lý sản phẩm,…

Payment gateway

Các store lunar ko sử dụng checkout trên web, mà chúng ta sẽ thông qua 1 payment gateway khác (Woocommerce), hay còn gọi là redirect pay. Giảm thiểu việc cài đặt các tài khoản trên hàng ngàn store, khó trong việc quản lý.

Installation

Đọc trong readme.md của project

Chú ý môi trường dev cần hỗ trợ Virtual Host, trên MacOS có thể sử dụng Valet, ngoài ra còn có các option khác như Laragon hoặc Herd hoặc

Tạo dev store với demo data

Trước hết cần phải setup hub trước, sau đó tạo 1 store trong hub.

Chú ý domain local có thể phải update file /etc/hosts để trỏ về ip của hub. File host sẽ tùy vào hệ điều hành.

Ví dụ domain của tenant là lunar1.test, cần add vào file host như sau:

127.0.0.1 lunar1.test

Chú ý chỉ nên sử dụng các tld test vd: .test, .local,…

Fill demo data

Chạy queue và khỏi tạo như bt (Ví dụ import từ Redbubble).
Download database từ 1 store đã được khởi tạo, vào upload ngược lại vào trong hub. Download images trong bunny của production storage, upload ngược lại sang dev storage và đổi tên thư mục trùng với domain của tenant ở local.

Khởi tạo 1 hub

Server requirements:

Ubuntu 22.04

Các bước khỏi tạo hub sẽ thực hiện trên Jenkins

Add deploy key dùng job: http://jenkins.sweb.vn/job/sweb/job/Add_user_deploy/
Provision server cho hub dùng job: http://jenkins.sweb.vn/job/lunar2/job/provision/

Triển khai 1 theme mới

Theme cho project sử dụng tailwindcss và alpinejs là chủ yếu. Node package manager sử dụng pnpm

Sử dụng command

php artisan make:theme demo

Trong đó shopee là tên theme muốn tạo. Sau đó 1 thư mục theme mới được tạo themes/demo

*Thư mục themes/demo được ignore nên ko được push lên git

Edit file packages/lunar-theme/config/themes.php, thêm tên file vào trong array themes.

Update file vite.config.js, thêm vào dòng themes/demo/css/app.css

Sau đó vào admin tại /lunar -> settings -> site settings Chọn theme là theme vừa tạo.

Cấu trúc 1 theme

- themes
	- demo # theme vừa tạo
		- css
			- app.css
		- views # nơi chứa các file views cho việc overwrite
			- home.blade.php
			- components
				- layouts
					- styles.blalde.php # file cấu hình style của theme
		- tailwind.config.js # file cấu hình tailwindcss

Cơ chế theme hoạt động theo kiểu kế thừa và overwrite, nội dung file template gốc trong resources/views

Cách đơn giản nhất là copy file và thư mục tương ứng từ theme gốc và chỉnh sửa lại style của từng phần

Chú ý nhớ commit code.

Các action thực hiện trên hệ thống

Chuyển website từ hub này sang hub khác.

Ví dụ bạn muốn chuyển store meocua.com từ hubA sang hubB, thực hiện các bước như sau:

Đăng nhập vào hubA, tải xuống file database của store meocua.com
Tạo 1 store với domain meocua.com trên hubB
Upload file database vừa tải trên hubA vào store vừa tạo trên hubB
Trỏ địa chỉ IP của domain sang hubB.
Xóa site cũ trên hubA

Toggle chế độ maintenance của 1 store

Có 2 cách để thực hiện:

Đăng nhập vào hub, và chọn Toggle maintenance của store.
Tắt bật trong admin General->Site Settings của từng store.

Auto backup

Database của các store sẽ được backup 1 tuần 1 lần, lưu trên Bunny.

Troubleshot

Import nhưng không truy cập được vào website

Kiểm tra domain đã được cấu hình trỏ về đúng hub server chưa
Website đã được khởi tạo trên hub hay chưa

Domain lỗi SSL

Không bao giờ xảy ra. Nếu xảy ra cần check log của caddy trên server 🤣

Lỗi khi generate ảnh thumbnail của Collection

Collection không có sản phẩm
Có thể server OG Image sida, cần check log /horizon để biết thêm thông tin.

Lỗi không import được sản phẩm từ Redbubble

Kiểm tra proxy của zenrows còn quota hay không
Redbubble có thay đổi cấu trúc api hay ko (hiện đang sử dụng graphQL của nó)

Upload ảnh bị lỗi.

Nếu là upload trong block của page builder, thử xóa block và tạo block mới để upload lại.
Chờ khoảng 1-2 phút sau và thử lại, nếu không được thì ping dev.

Chức năng auto import không hoạt động

Store trên hub đến từ nhiều nguồn, có thể được import từ bên Woocommerce, do đó có thể không được config đúng như khi khởi tạo từ ban đầu.

Lunar HQ

Server trung tâm dành cho việc setup các common stuff cho hệ thống store. Hiện tại các function chưa được quy hoạch và đang để ở những website khác nhau.

Hiện tại HQ có các api sau:

Api cho phép tạo Google Analytics scripts để nhúng vào các website mới khỏi tạo

TDA Weki

Explorer

architecture