Triển khai wiki cùng domain

Hướng dẫn vận hành deploy wiki tĩnh bên cạnh app Laravel Booking Dental.

1. Build

Trên máy build hoặc CI:

cd booking-dental-admin-wiki
npm ci
npm run check:images
npm run docs:build

Output: docs/.vitepress/dist/

Subpath /docs/ (mặc định)

VITEPRESS_BASE=/docs/ npm run docs:build

URL ví dụ: https://booking.example.com/docs/

Subdomain

VITEPRESS_BASE=/ npm run docs:build

URL ví dụ: https://docs.booking.example.com/

1b. Docker (nginx trong container)

Từ thư mục repo:

docker compose build
docker compose up -d

Mặc định build với VITEPRESS_BASE=/ (wiki ở gốc URL), map cổng 8080 → mở http://localhost:8080/.

Để build giống bản subpath /docs/ cho reverse-proxy:

VITEPRESS_BASE=/docs/ docker compose build --no-cache
docker compose up -d

Tuỳ chọn: sao chép .env.docker.example thành .env và chỉnh WIKI_PORT, VITEPRESS_BASE.

2. Copy lên server

rsync -av --delete docs/.vitepress/dist/ user@server:/var/www/booking-dental-wiki/

3. Cấu hình Nginx

Subpath

location /docs/ {
    alias /var/www/booking-dental-wiki/;
    try_files $uri $uri/ /docs/index.html;
}

Đảm bảo SSL certificate chung với app chính.

Subdomain

Server block riêng với root /var/www/booking-dental-wiki; và try_files $uri $uri/ /index.html;

4. Gắn menu Filament (thủ công)

Trong repo be-booking-dental, mở app/Providers/Filament/AdminPanelProvider.php và thêm navigation item:

use Filament\Navigation\NavigationItem;

// trong panel() chain:
->navigationItems([
    NavigationItem::make('Hướng dẫn')
        ->url('https://YOUR-DOMAIN/docs/', shouldOpenInNewTab: true)
        ->icon('heroicon-o-book-open')
        ->group('Quản trị hệ thống')
        ->sort(100),
])

Thay YOUR-DOMAIN bằng domain production. Mở tab mới (shouldOpenInNewTab: true) để user không mất session admin.

5. Checklist sau deploy

• [ ] Mở URL wiki — trang chủ và sidebar load đủ
• [ ] Ảnh screenshot hiển thị (không 404)
• [ ] Search nội bộ VitePress hoạt động
• [ ] Link menu Filament trỏ đúng URL HTTPS
• [ ] Thay placeholder bằng ảnh thật từ staging (nếu còn watermark PLACEHOLDER)

6. Cập nhật sau này

1. Sửa markdown trong repo wiki
2. Chụp lại screenshot nếu UI đổi
3. npm run docs:build → rsync lại dist

Chi tiết kỹ thuật (English): xem file agent/methodology/deploy-same-domain.md trong cùng repo wiki (không publish lên site).