Tổng Hợp VPS

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

Tự host Wiki.js cho dev team VN trên VPS Ubuntu: markdown editor, Git sync, OAuth, search, theming, backup. Thay Confluence/Notion tiết kiệm 90% chi phí.

Thanh Nguyễn Cập nhật Đăng 7 phút đọc 7 khối lệnh

Setup Wiki.js cho dev team trên VPS: docs nội bộ ngon
Mục lục bài viết
  1. 1. Vì sao chọn Wiki.js?
  2. 2. Yêu cầu VPS
  3. 3. Setup Docker Compose
  4. 4. Cấu hình OAuth Google login
  5. 5. Tạo trang đầu tiên và structure
  6. 6. Git sync 2-chiều
  7. 7. Search full-text với Elasticsearch
  8. 8. Phân quyền và group
  9. 9. Mermaid diagram và code highlight
  10. 10. Backup và disaster recovery
  11. 11. Theming và custom CSS
  12. 12. Migrate từ Notion/Confluence
  13. FAQ

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?

ToolPricing 10 userMarkdownSelf-hostOAuth
Wiki.js250k VPSCóCó (chính)Có (8 provider)
Notion80$/thángCóKhôngCó
Confluence Cloud60$/thángCó nhưng yếuServer đã EOLCó
BookStack250k VPSCóCóCó
Outline200k VPSCóCó (Docker)Có

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

Terminal3. Setup Docker Composebash
# Cài Dockercurl -fsSL https://get.docker.com | shmkdir -p /opt/wikijs/{postgres,uploads}cd /opt/wikijs
File cấu hình3. Setup Docker Composeyaml
# docker-compose.ymlservices:  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:
PowerShell3. Setup Docker Composepowershell
# Caddyfiledocs.your-domain.com {    reverse_proxy wiki:3000    encode gzip    header Strict-Transport-Security "max-age=31536000;"} # .envPOSTGRES_PASSWORD=$(openssl rand -base64 32 | tr -d /=+)
Terminal3. Setup Docker Composebash
docker compose up -ddocker 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:

File cấu hình7. Search full-text với Elasticsearchyaml
# Thêm vào docker-compose.ymlelasticsearch:  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

Terminal9. Mermaid diagram và code highlightbash
# Trong page markdown, dùng fenced code block mermaid```mermaidsequenceDiagram    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

Terminal10. Backup và disaster recoverybash
# /opt/wikijs/backup.sh#!/bin/bashDATE=$(date +%F)mkdir -p /backup/wikidocker compose -f /opt/wikijs/docker-compose.yml exec -T postgres   pg_dump -U wiki wiki | gzip > /backup/wiki/wiki-$DATE.sql.gztar -czf /backup/wiki/uploads-$DATE.tar.gz -C /opt/wikijs uploadsfind /backup/wiki -mtime +14 -delete # Cron 2h sáng0 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.

Chia sẻ:Facebook

Thanh Nguyễn

TND

Tư vấn bản quyền, VPS và máy chủ kèm hóa đơn VAT, hợp đồng đầy đủ cho doanh nghiệp.