Setup Wiki.js cho dev team trên VPS: docs nội bộ ngon

Team dev VN luôn đau đầu với docs nội bộ: Notion đắt cho team đông, Confluence càng đắt, GitHub Wiki thiếu tính năng, Google Docs không phù hợp technical. Wiki.js open source đáp ứng: markdown editor, Git sync, OAuth, search, theming, multi-user role, asset upload. Self-host trên VPS Ubuntu chỉ 250k/tháng cho team 50 người.

Bài này hướng dẫn setup Wiki.js production-ready từ A-Z: Docker Compose, Postgres, Caddy auto SSL, OAuth Google, Git sync với GitHub. Đã chạy production cho 3 client trong 18 tháng, không downtime đáng kể.

Mục tiêu cuối bài: bạn có Wiki.js chạy HTTPS trên domain riêng, login Google OAuth, page đầu tiên publish, Git sync về repo backup, search hoạt động. Tổng setup 30 phút.

1. Vì sao chọn Wiki.js?

Wiki.js mạnh nhất ở: Git sync 2-chiều (push markdown về Git, pull update từ Git), search Elasticsearch built-in, theming dễ tùy biến, ngôn ngữ giao diện đa ngôn ngữ (có tiếng Việt).

2. Yêu cầu VPS

• RAM: 2GB tối thiểu (Wiki.js 500MB + Postgres 200MB + buffer).
• vCPU: 2.
• SSD: 40GB.
• Ubuntu 24.04 LTS, Docker.
• Domain: docs.your-domain.com trỏ A record về IP VPS.

3. Setup Docker Compose

# Cài Docker
curl -fsSL https://get.docker.com | sh
mkdir -p /opt/wikijs/{postgres,uploads}
cd /opt/wikijs

# docker-compose.yml
services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: wiki
      POSTGRES_USER: wiki
      POSTGRES_PASSWORD: $POSTGRES_PASSWORD
    volumes:
      - ./postgres:/var/lib/postgresql/data

  wiki:
    image: ghcr.io/requarks/wiki:2
    restart: unless-stopped
    depends_on: [postgres]
    environment:
      DB_TYPE: postgres
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USER: wiki
      DB_PASS: $POSTGRES_PASSWORD
      DB_NAME: wiki
    volumes:
      - ./uploads:/wiki/data/content
    ports:
      - "127.0.0.1:3000:3000"

  caddy:
    image: caddy:2-alpine
    restart: unless-stopped
    ports: ["80:80", "443:443"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data

volumes:
  caddy_data:

# Caddyfile
docs.your-domain.com {
    reverse_proxy wiki:3000
    encode gzip
    header Strict-Transport-Security "max-age=31536000;"
}

# .env
POSTGRES_PASSWORD=$(openssl rand -base64 32 | tr -d /=+)

docker compose up -d
docker compose logs -f wiki

# Truy cập https://docs.your-domain.com
# Setup wizard: tạo admin (email + password), chọn site title, save

4. Cấu hình OAuth Google login

• Vào Google Cloud Console -> Credentials -> Create OAuth 2.0 Client.
• Type: Web application. Authorized redirect URIs: https://docs.your-domain.com/login/google/callback.
• Copy Client ID + Client Secret.
• Trong Wiki.js Admin -> Authentication -> Add Google strategy.
• Paste Client ID + Secret, restrict domain (vd: @your-company.com), save.
• Test: logout, login lại bằng Google.

Restrict domain rất quan trọng - chỉ employee company được login, không ai ngoài truy cập. Có thể combine với GitHub OAuth cho team dev có GH org.

5. Tạo trang đầu tiên và structure

Wiki.js dùng path /like-this. Structure phổ biến cho dev team VN:

• /onboarding - tài liệu cho new hire.
• /engineering/coding-standards - guidelines code.
• /engineering/architecture - sơ đồ system.
• /engineering/runbooks - troubleshoot operations.
• /product/specs - feature spec.
• /hr - chính sách nhân sự.
• /meeting-notes/2026 - biên bản họp.

Editor markdown của Wiki.js có preview live, drag-drop image upload, code block syntax highlight 100+ language, Mermaid diagram inline, table editor visual. Đủ cho 99% nhu cầu docs.

6. Git sync 2-chiều

• Admin -> Storage -> Add Git.
• Repository URL: [email protected]:your-org/docs-mirror.git.
• SSH key: generate trên VPS, add public key vào GitHub deploy key.
• Mode: push (gửi mọi page lên GitHub), pull (đọc từ GitHub về), bidirectional.
• Interval: 5 phút (auto sync).

Lợi ích Git sync: backup miễn phí trên GitHub, version history vĩnh viễn, dev có thể edit qua VS Code + push, review PR cho docs nhạy cảm. Mình hay setup branch protection trên main, mọi update phải PR.

7. Search full-text với Elasticsearch

Mặc định Wiki.js dùng Postgres full-text search (đủ <1000 page). Trên 1000 page, switch Elasticsearch:

# Thêm vào docker-compose.yml
elasticsearch:
  image: elasticsearch:8.15.0
  environment:
    discovery.type: single-node
    xpack.security.enabled: "false"
    ES_JAVA_OPTS: "-Xms512m -Xmx512m"
  volumes:
    - es_data:/usr/share/elasticsearch/data

volumes:
  es_data:

Trong Wiki.js Admin -> Search -> chọn Elasticsearch, host: elasticsearch:9200. Lưu ý: Elasticsearch ngốn 1GB RAM riêng, VPS phải có ít nhất 4GB tổng.

8. Phân quyền và group

• Admin -> Groups -> tạo group "Engineers", "Product", "HR".
• Mỗi group có rules: regex path access (Engineers /engineering/*, HR /hr/*).
• Action: read, write, delete riêng từng path.
• User tự động join group dựa trên email pattern hoặc OAuth claim.

Phân quyền chi tiết giúp HR không thấy roadmap engineering, dev không edit chính sách HR. Reduce blast radius khi account leak.

9. Mermaid diagram và code highlight

# Trong page markdown, dùng fenced code block mermaid
```mermaid
sequenceDiagram
    Client->>API: POST /login
    API->>DB: SELECT user
    DB-->>API: user data
    API-->>Client: JWT token
```

Mermaid render inline. Hỗ trợ flowchart, sequence, ER, Gantt, mindmap. Code block syntax highlight 100+ language. Markdown extensions: footnote, definition list, abbreviations, TOC tự động.

10. Backup và disaster recovery

# /opt/wikijs/backup.sh
#!/bin/bash
DATE=$(date +%F)
mkdir -p /backup/wiki
docker compose -f /opt/wikijs/docker-compose.yml exec -T postgres 
  pg_dump -U wiki wiki | gzip > /backup/wiki/wiki-$DATE.sql.gz
tar -czf /backup/wiki/uploads-$DATE.tar.gz -C /opt/wikijs uploads
find /backup/wiki -mtime +14 -delete

# Cron 2h sáng
0 2 * * * /opt/wikijs/backup.sh

Combine với snapshot 1-click VPS TND (7 ngày tự động), Git sync backup nội dung lên GitHub. Triple protection. Test restore quý 1 lần.

11. Theming và custom CSS

• Admin -> Theme -> chọn primary color theo brand.
• Inject Code (custom JS/CSS) cho header logo, footer copyright.
• Markdown CSS: editor preview style.
• Dark mode tự động theo prefers-color-scheme browser.

12. Migrate từ Notion/Confluence

• Notion export -> Markdown & CSV (Settings -> Workspace -> Export). Wiki.js import từng file qua Storage -> Local File System.
• Confluence export XML, dùng tool notion-to-wikijs hoặc confluence-to-md trên npm.
• Image asset: upload qua Wiki.js asset manager, update path trong markdown.
• Manual review redirect, broken link, formatting.

Migrate 500 page Notion mất 1-2 ngày work. Worth nó vì tiết kiệm 70$/tháng sau đó.

FAQ

Wiki.js v3 stable chưa?

Tháng 5/2026 v3 vẫn beta. Mình production v2.5 LTS, ổn định, đủ tính năng. v3 rebuild full Vue 3 + Fastify, performance tốt hơn nhưng còn thiếu plugin migration. Stick v2 cho production, theo dõi v3 cho project mới khi stable.

Wiki.js có hỗ trợ tiếng Việt không?

Có. UI 17 ngôn ngữ gồm Vietnamese (Admin -> General -> Language -> vi). Search Postgres FTS xử lý tốt accent. Content viết tiếng Việt rendering chuẩn. Mermaid diagram label tiếng Việt OK.

Có thể chạy Wiki.js cùng Postgres existing không?

Có. Tạo DB riêng wiki trong Postgres existing, grant user. Sửa env DB_HOST trỏ tới Postgres host. Tiết kiệm RAM nếu đã có Postgres cho app khác. Lưu ý: backup riêng từng DB.

Wiki.js có search tốt cho 10000 page không?

Postgres FTS đủ tới ~5000 page. Trên đó cần Elasticsearch (thêm 1GB RAM). Cảm nhận: tìm cụm từ exact <200ms với Elasticsearch trên 50k page. Postgres FTS chậm hơn 3-5x nhưng vẫn dùng được. Mới đầu start Postgres, scale lên Elasticsearch khi cần.

Có API REST/GraphQL không?

Có GraphQL API endpoint /graphql. Cho phép query/mutation page, user, group, asset. Phù hợp tích hợp với n8n (tạo page tự động khi merge PR), Slack bot (search wiki từ Slack), CI/CD (auto generate API docs từ swagger spec).

Wiki.js có mobile app không?

Không official app. Web responsive tốt, mở trên Chrome mobile dùng OK cho đọc. Edit mobile khá khó với markdown. Khuyến nghị: cài PWA (icon trên home screen iOS/Android), offline cache page đã visit. Đủ cho 90% mobile use case.