Deployment

Target: deploy yellow-bank-soal-docs ke VPS aaPanel (klien) sebagai static site. Stack: Bun (untuk build) + Nginx (untuk serve static files via aaPanel). Tidak ada Docker, tidak ada Node.js runtime persistent, tidak ada PM2.

Output bun run build adalah pure static HTML/CSS/JS di .docu/dist/. Setelah build, Nginx langsung serve file tersebut — tidak butuh proses yang jalan terus.

Prasyarat di VPS Klien

Tidak perlu Node.js, tidak perlu PM2, tidak perlu Python.

Step 1: Install Bun di VPS

1. Buka aaPanel → sidebar kiri → Terminal
2. Jalankan command:

curl -fsSL https://bun.sh/install | bash

3. Reload shell:

source ~/.bashrc

4. Verifikasi:

bun --version

Harusnya muncul versi (mis. 1.3.x).

Resource Bun: ~50MB di disk, tidak ada service yang jalan. Bun hanya dipakai saat build, setelah itu idle.

Step 2: Clone Repo Docs

1. Di Web Terminal, pindah ke document root aaPanel:

cd /www/wwwroot/

2. Clone repo (public, tanpa auth):

git clone https://git.backoffice.biz.id/dwindown/yellow-bank-soal-docs.git soal-docs.theyellowjacket.id

Catatan: kalau clone via HTTPS gagal (umumnya karena git butuh konfigurasi), pakai URL SSH dengan port 2222:

bash

CopyReady to copy code

git clone ssh://[email protected]:2222/dwindown/yellow-bank-soal-docs.git soal-docs.theyellowjacket.id

Repo public, jadi SSH key tidak wajib.

3. Masuk ke folder:

cd soal-docs.theyellowjacket.id

Step 3: Install Dependencies + Patch Flame

bun install

Penting: command ini akan otomatis meng-apply patch flame (gesture navigation mermaid) dari folder patches/. Patch ini persistent — terdaftar di package.json → patchedDependencies.

Verifikasi patch ter-apply:

grep -c "handleWheel\|handlePointerDown" node_modules/@docubook/mdx-content/dist/index.js

Harusnya muncul angka > 0 (sekitar 4-6).

Step 4: Build Pertama

bun run build

Tunggu sampai muncul:

✓ Built 32 pages (0 cached)
✓ Search index generated (794 records)

Hasil build ada di .docu/dist/. Folder ini yang akan dilayani Nginx.

Verifikasi struktur output:

ls -la .docu/dist/

Harus ada: index.html, 404.html, docs/, assets/.

Step 5: Setup Static Site di aaPanel

5.1 Buat Website Baru

1. aaPanel → Website → Add Site
2. Isi form:
   • Type: PHP Site (atau Static Site — pilih yang ada)
   • Domain: soal-docs.theyellowjacket.id
   • Root Directory: klik "Browse" → pilih /www/wwwroot/soal-docs.theyellowjacket.id/.docu/dist
   • PHP Version: Pure Static (kalau ada opsi) atau apapun (tidak dipakai)
   • Database: None
3. Klik Submit

⚠️ Penting: Root directory harus mengarah ke .docu/dist/, bukan ke root repo. Kalau salah, halaman tidak akan muncul.

5.2 (Opsional) Hapus Default Index aaPanel

aaPanel biasanya buat file index.html default di root site. Karena kita pakai .docu/dist/ yang sudah punya index.html, hapus default-nya:

# Lewat Web Terminal
ls /www/wwwroot/soal-docs.theyellowjacket.id/.docu/dist/index.html
# kalau ada, berarti sudah benar

Step 6: Setup SSL (HTTPS)

1. aaPanel → Website → klik site soal-docs.theyellowjacket.id → Settings
2. Tab SSL → pilih Let's Encrypt
3. Klik Apply
4. Tunggu sampai issued (biasanya < 1 menit)
5. Centang Force HTTPS untuk redirect HTTP → HTTPS

Setelah ini, akses https://soal-docs.theyellowjacket.id harus muncul landing page docs.

Step 7: Konfigurasi Nginx untuk Routing DocuBook

DocuBook menggunakan URL seperti /docs/konsep/alur (tanpa .html). Nginx perlu di-config untuk auto-append .html ke URL yang tidak punya extension.

1. aaPanel → Website → klik site → Settings → Config File
2. Cari blok location / dan tambahkan directive try_files:

location / {
    try_files $uri $uri/ $uri.html /404.html;
}

3. Save config
4. aaPanel akan otomatis reload Nginx

Full example (sesuaikan dengan config aaPanel Anda):

server {
    listen 80;
    listen 443 ssl;
    server_name soal-docs.theyellowjacket.id;

    root /www/wwwroot/soal-docs.theyellowjacket.id/.docu/dist;
    index index.html;

    # SSL config (auto-generated by aaPanel)
    # ssl_certificate ...
    # ssl_certificate_key ...

    location / {
        try_files $uri $uri/ $uri.html /404.html;
    }

    # Cache static assets aggressively
    location ~* \.(js|css|svg|png|jpg|jpeg|gif|ico|woff2?)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # HTML tidak di-cache (untuk update konten langsung reflect)
    location ~* \.html$ {
        add_header Cache-Control "no-cache, must-revalidate";
    }
}

Step 8: Buat Deploy Script untuk Update

Script ini akan dijalankan tiap kali mau update docs.

8.1 Buat File Script

Di Web Terminal:

cat > /www/wwwroot/soal-docs.theyellowjacket.id/deploy.sh << 'EOF'
#!/bin/bash
set -e

SITE_DIR="/www/wwwroot/soal-docs.theyellowjacket.id"
cd "$SITE_DIR"

echo "=== Pull latest changes ==="
git pull origin main

echo "=== Install dependencies (auto-apply patches) ==="
bun install --frozen-lockfile

echo "=== Clean previous build ==="
bunx flame clean

echo "=== Build ==="
bun run build

echo "=== Done at $(date) ==="
ls -la .docu/dist/ | head -10
EOF

chmod +x /www/wwwroot/soal-docs.theyellowjacket.id/deploy.sh

8.2 Test Script

Jalankan sekali untuk pastikan jalan:

/www/wwwroot/soal-docs.theyellowjacket.id/deploy.sh

Kalau berakhir dengan === Done at <date> === dan list file .docu/dist/, berarti sukses.

Step 9: Setup aaPanel Cron (Update dengan 1 Klik)

1. aaPanel → Cron (sidebar)
2. Klik Add Cron
3. Isi:
   • Task Type: Shell Script
   • Task Name: Update Docs yellow-bank-soal
   • Execution Cycle: Manual (jangan set waktu — kita trigger manual)
   • Script Content:
     bash

     CopyReady to copy code

     /www/wwwroot/soal-docs.theyellowjacket.id/deploy.sh
     

4. Submit

Sekarang tiap mau update docs:

1. Buka aaPanel → Cron
2. Cari task Update Docs yellow-bank-soal
3. Klik tombol Execute (▶️) di sebelah kanan
4. Tunggu ~10-15 detik, refresh browser docs → konten baru muncul

Tidak perlu SSH, tidak perlu buka Web Terminal tiap kali.

Verifikasi Deployment

Buka browser, akses:

Troubleshooting

Halaman blank / 404 di semua URL

Kemungkinan: root directory salah atau file index.html tidak ada.

Cek:

ls /www/wwwroot/soal-docs.theyellowjacket.id/.docu/dist/index.html

Kalau tidak ada, jalankan ulang bun run build di Web Terminal.

Halaman /docs/konsep/alur 404 tapi /docs/konsep/alur.html bisa diakses

Kemungkinan: Nginx try_files belum dikonfigurasi untuk auto-append .html.

Fix: ulangi Step 7, pastikan try_files $uri $uri/ $uri.html /404.html; ada di config.

SSL gagal issue

Kemungkinan: domain belum pointing ke IP VPS, atau port 80 belum terbuka.

Cek:

# DNS resolve
dig soal-docs.theyellowjacket.id +short

# Port 80 open
curl -I http://soal-docs.theyellowjacket.id

Build gagal dengan error patch

Kemungkinan: patches/ folder tidak ikut ter-commit ke git, atau bun.lock corrupt.

Fix:

cd /www/wwwroot/soal-docs.theyellowjacket.id
git pull
rm -rf node_modules bun.lock
bun install
bun run build

Mermaid gesture (scroll zoom, drag pan) tidak jalan

Kemungkinan: patch flame tidak ter-apply, atau browser cache.

Cek:

grep -c "handleWheel" node_modules/@docubook/mdx-content/dist/index.js

Harusnya > 0. Kalau 0, hapus node_modules lalu bun install ulang.

Browser cache: hard refresh Cmd+Shift+R atau Ctrl+Shift+R.

Backup & Maintenance

Backup

Yang penting di-backup cuma source repo (sudah di git). Output build bisa di-regenerate kapan saja.

# Backup manual (jarang dibutuhkan karena ada git)
tar -czf docs-backup-$(date +%Y%m%d).tar.gz \
    --exclude=node_modules \
    --exclude=.docu \
    /www/wwwroot/soal-docs.theyellowjacket.id/

Update Bun

Sekali per beberapa bulan, update Bun untuk fitur/security:

bun upgrade

Disk Space

Cek penggunaan disk:

du -sh /www/wwwroot/soal-docs.theyellowjacket.id/
du -sh /www/wwwroot/soal-docs.theyellowjacket.id/node_modules/
du -sh /www/wwwroot/soal-docs.theyellowjacket.id/.docu/

Total biasanya ~150-200MB (node_modules + build output). Tidak signifikan untuk VPS 16GB.

Security Considerations

Tambahkan ke Nginx config untuk keamanan:

# Block akses ke file/folder sensitif
location ~ /\.(git|env|docu) {
    deny all;
    return 404;
}

location ~ /(node_modules|patches) {
    deny all;
    return 404;
}

Update Workflow Summary

Sekali setup (Step 1-9): ~30 menit.

Setiap update docs (jarang):

1. Commit + push ke git-ssh.backoffice.biz.id:2222/dwindown/yellow-bank-soal-docs.git dari lokal
2. Buka aaPanel klien → Cron → cari task "Update Docs"
3. Klik Execute
4. Tunggu 10-15 detik
5. Refresh browser → konten baru muncul

Tidak perlu SSH, tidak perlu build lokal, tidak perlu upload manual.

Bacaan Lanjut

• Operasional → Instalasi — setup environment lokal untuk development
• Operasional → Konfigurasi — env vars & config
• DocuBook README — upstream documentation