Zorio Developer Portal — docs.zorio.vn (Deploy Package)

Gói cài đặt static site cho docs.zorio.vn — dùng VitePress SSG, deploy được lên Apache 2.4+, nginx, hoặc shared hosting.

Version: 1.1 · Build: VitePress · Kích thước: ~16 MB (88 trang VI + EN)

---

📦 Cấu trúc gói

zorio-docs-package/
├── docs.zorio.vn/                     # ← Thư mục static site (copy vào /var/www)
│   ├── index.html
│   ├── 404.html
│   ├── assets/, api/, auth/, en/, ...
│   ├── favicon.png, logo.png
│   └── llms.txt, hashmap.json, sitemap.xml
│
├── docs.zorio.vn.apache.conf          # ← Apache VirtualHost (root access)
├── nginx.docs.zorio.vn.conf           # ← Nginx VirtualHost (tham chiếu)
├── .htaccess                          # ← Apache shared hosting (KHÔNG cần root)
└── README-INSTALL.md                  # File này

---

🚀 Cài đặt Apache (root access — khuyến nghị)

1. Chuẩn bị

Bật các module cần thiết:

sudo a2enmod ssl rewrite headers deflate expires mime
sudo systemctl restart apache2

2. Copy static files

sudo mkdir -p /var/www/docs.zorio.vn
sudo cp -r docs.zorio.vn/* /var/www/docs.zorio.vn/
sudo chown -R www-data:www-data /var/www/docs.zorio.vn
sudo chmod -R 755 /var/www/docs.zorio.vn

3. Cài VirtualHost

sudo cp docs.zorio.vn.apache.conf /etc/apache2/sites-available/docs.zorio.vn.conf
sudo a2ensite docs.zorio.vn.conf
sudo apache2ctl configtest    # Verify cú pháp
sudo systemctl reload apache2

4. Cài SSL cert (Let's Encrypt)

sudo apt install certbot python3-certbot-apache
sudo certbot --apache -d docs.zorio.vn --agree-tos -m admin@zorio.vn --redirect

Sau khi cert cấp thành công, certbot --apache sẽ tự động thêm SSL directives vào VirtualHost.

Nếu đã có wildcard cert *.zorio.vn, sửa 2 dòng SSLCertificateFile / SSLCertificateKeyFile trong docs.zorio.vn.apache.conf trỏ tới /etc/letsencrypt/live/zorio.vn/ thay vì docs.zorio.vn/.

5. Verify

curl -I https://docs.zorio.vn/
# HTTP/2 200
# strict-transport-security: max-age=63072000; includeSubDomains

---

🌐 Cài đặt shared hosting (không có root — dùng .htaccess)

Nếu hosting provider (cPanel, Plesk, DirectAdmin...) không cho sửa VirtualHost:

1. Upload toàn bộ nội dung docs.zorio.vn/ vào document root (thường là public_html/ hoặc www/).
2. Copy .htaccess vào cùng thư mục document root (cạnh index.html).
3. Verify mod_rewrite, mod_headers, mod_deflate, mod_expires đã enable ở server level. Nếu chưa, liên hệ hosting support hoặc bật qua cPanel.
4. Truy cập https://docs.zorio.vn/ — kiểm tra /api/pbx/extensions route (không có file thực) có redirect được về SPA không.

Nếu SPA fallback không hoạt động (404 khi refresh trang con), có thể do AllowOverride None — cần chuyển sang hosting cho phép .htaccess overrides.

---

🔧 Cài đặt nginx (thay Apache)

Dùng nginx.docs.zorio.vn.conf sẵn có (đã test trên production docs.zorio.vn gốc):

sudo cp -r docs.zorio.vn/* /var/www/docs.zorio.vn/
sudo cp nginx.docs.zorio.vn.conf /etc/nginx/sites-available/docs.zorio.vn.conf
sudo ln -sf /etc/nginx/sites-available/docs.zorio.vn.conf /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

# Let's Encrypt
sudo certbot --nginx -d docs.zorio.vn --agree-tos -m admin@zorio.vn --redirect

---

🧪 Verify sau cài đặt

# 1. Home page
curl -sI https://docs.zorio.vn/ | head -5

# 2. Static asset cache header (30 days immutable)
curl -sI https://docs.zorio.vn/assets/style.css | grep -i cache-control

# 3. Markdown file với CORS
curl -sI https://docs.zorio.vn/llms.txt | grep -iE "access-control|content-type"

# 4. SPA fallback (route không có file → phải trả 200 + index.html)
curl -sI https://docs.zorio.vn/api/pbx/extensions

# 5. 404 page
curl -sI https://docs.zorio.vn/khong-ton-tai

Expected:

• (1) HTTP/2 200 + strict-transport-security
• (2) Cache-Control: public, max-age=2592000, immutable
• (3) Access-Control-Allow-Origin: * + Content-Type: text/plain; charset=UTF-8
• (4) HTTP/2 200 (không phải 404)
• (5) HTTP/2 404 + Body chứa 404.html

---

🔄 Cập nhật nội dung (rebuild + redeploy)

Khi nội dung docs thay đổi, rebuild ở Zorio source repo (VitePress) rồi:

# Trên máy dev:
cd /opt/zorio-docs
npm run build
tar czf zorio-docs-static.tar.gz .vitepress/dist/

# Trên server public:
scp zorio-docs-static.tar.gz public-server:/tmp/
ssh public-server
sudo tar xzf /tmp/zorio-docs-static.tar.gz -C /var/www/docs.zorio.vn --strip-components=2
sudo chown -R www-data:www-data /var/www/docs.zorio.vn
sudo systemctl reload apache2   # hoặc nginx

---

📞 Support

Vấn đề triển khai → contact quản trị viên hệ thống Zorio. Chi tiết cấu trúc VitePress → xem README.md ở source zorio-docs repo.