Deploy docs lên Cloudflare

Trang này là runbook để đưa docs-site lên Cloudflare free tier, đề xuất domain docs.holilihu.online.

Theo rule repo, agent không tự deploy production và không tự trỏ DNS. Phần dưới là cấu hình + checklist để bạn hoặc manager chạy sau khi đã xác nhận tài khoản Cloudflare, zone holilihu.online, quyền DNS và quyền Pages/Workers.

Chọn nền tảng nào?

Lựa chọn Khi dùng Ưu điểm File cấu hình
Cloudflare Pages Khuyến nghị cho docs Jekyll tĩnh Miễn phí, custom domain dễ, Direct Upload/Git deploy đều được docs-site/wrangler.toml
Cloudflare Workers Static Assets Dự phòng khi cần logic edge sau này Có thể thêm Worker code/cache/routing tùy biến docs-site/wrangler.worker.example.toml

Với docs hiện tại, Cloudflare Pages là hướng gọn nhất vì Jekyll build sẵn ra thư mục _site.

Build local trước khi upload 

cd E:\Sach\Sua\LMS_hohulili\docs-site
bundle exec jekyll build

Kết quả cần có:

  • docs-site/_site/index.html
  • docs-site/_site/_headers
  • docs-site/_site/assets/images/lms-directory-tree.svg
  • docs-site/_site/assets/images/lms-file-flow.svg

Deploy bằng Cloudflare Pages Direct Upload

Direct Upload phù hợp khi muốn build ở máy local/CI rồi upload thư mục _site.

cd E:\Sach\Sua\LMS_hohulili\docs-site
npx wrangler login
npx wrangler pages project create

Khi được hỏi:

Prompt Giá trị đề xuất
Project name lms-hohulili-docs
Production branch main

Sau đó deploy:

npx wrangler pages deploy _site --project-name lms-hohulili-docs --branch main

Nếu chỉ muốn preview trước khi gắn domain:

npx wrangler pages deploy _site --project-name lms-hohulili-docs --branch docs-preview

Preview sẽ có dạng docs-preview.lms-hohulili-docs.pages.dev. Production thường có dạng lms-hohulili-docs.pages.dev.

Preview hiện tại

Preview an toàn đã được tạo trên Cloudflare Pages:

  • Project: lms-hohulili-docs
  • Branch: docs-preview-20260614
  • Stable preview alias: https://docs-preview-20260614.lms-hohulili-docs.pages.dev

Preview dùng để kiểm tra nội dung trước khi đẩy production. Nếu không muốn preview bị index, có thể bật Cloudflare Access hoặc đặt branch preview riêng với header noindex; production docs.holilihu.online hiện được cấu hình indexable.

Custom domain hiện tại

Custom domain chính thức đã chọn cho tài liệu LMS:

  • Domain: https://docs.holilihu.online
  • Pages project: lms-hohulili-docs
  • Production branch: main
  • DNS record: CNAME docs -> lms-hohulili-docs.pages.dev
  • Proxy: enabled

Domain này dùng chung nhận diện với holilihu.online: favicon/logo lấy từ LMS Maritime, Open Graph dùng ảnh chia sẻ chung và production docs cho phép index.

SEO sau khi gắn domain

Hạng mục File Trạng thái mong muốn
Robots docs-site/robots.txt Allow: / và trỏ tới https://docs.holilihu.online/sitemap.xml
Header crawl docs-site/_headers X-Robots-Tag: index, follow
Canonical/OG/Twitter docs-site/_config.yml, docs-site/_includes/head_custom.html Có canonical, social image, favicon và apple icon
Structured data docs-site/_includes/head_custom.html JSON-LD Organization, WebSite, WebPage
Sitemap docs-site/sitemap.xml Sinh URL cho trang học và report HTML chính

Sau deploy, kiểm nhanh:

curl -I https://docs.holilihu.online/
curl https://docs.holilihu.online/robots.txt
curl https://docs.holilihu.online/sitemap.xml

Không đưa mật khẩu DB, .env*, screenshot tạm hoặc cache vào docs public.

Gắn custom domain docs.holilihu.online

Trong Cloudflare Dashboard:

  1. Vào Workers & Pages.
  2. Chọn project lms-hohulili-docs.
  3. Mở Custom domains.
  4. Chọn Set up a domain.
  5. Nhập docs.holilihu.online.
  6. Nếu zone holilihu.online đang nằm trong cùng Cloudflare account, Cloudflare thường tự tạo record cần thiết.
  7. Nếu DNS ở nơi khác, tạo CNAME:
Type: CNAME
Name: docs
Target: lms-hohulili-docs.pages.dev
Proxy: enabled nếu DNS ở Cloudflare

Không nên chỉ tự tạo CNAME rồi bỏ qua bước Custom domains trong Pages. Cloudflare docs cảnh báo domain có thể không resolve đúng nếu chưa được associate với Pages project.

Phương án Worker static assets

Chỉ dùng khi muốn route qua Worker thay vì Pages. Không ghi đè wrangler.toml Pages mặc định; dùng file example:

cd E:\Sach\Sua\LMS_hohulili\docs-site
bundle exec jekyll build
npx wrangler deploy --config wrangler.worker.example.toml

Sau khi deploy Worker preview ổn mới cân nhắc custom domain. Worker phù hợp nếu sau này cần thêm edge logic như redirect, auth nhẹ, cache rule tùy biến.

GitHub/CI gợi ý

Nếu manager muốn deploy tự động:

  1. Dùng GitHub Actions với Ruby + Bundler để build docs-site.
  2. Lưu secret CLOUDFLARE_API_TOKEN và CLOUDFLARE_ACCOUNT_ID.
  3. Chạy npx wrangler pages deploy docs-site/_site --project-name lms-hohulili-docs --branch main.

Không commit token hoặc .env*.

Smoke sau khi deploy 

curl -I https://docs.holilihu.online/
curl -I https://docs.holilihu.online/study/readiness-audit.html
curl -I https://docs.holilihu.online/assets/images/lms-directory-tree.svg
curl https://docs.holilihu.online/robots.txt
curl https://docs.holilihu.online/sitemap.xml

Cần kiểm:

  • Status 200 cho trang chủ, audit page và SVG.
  • Header có X-Content-Type-Options: nosniff.
  • Header có X-Robots-Tag: index, follow cho production docs.
  • Browser không lỗi font tiếng Việt.
  • Search được Sơ đồ thư mục, directory map, ARB, 107 migration SQL.
  • Social preview có og:image dùng ảnh chung Holilihu.
  • Không để docs domain trỏ nhầm về LMS app chính ở holilihu.online.

Nguồn Cloudflare đã đối chiếu