VPS cho BookStack: wiki nhóm tự host

Tài liệu của nhóm thường chết theo một trong hai cách: rải rác trong các luồng chat không ai tìm được, hoặc bị chôn trong một wiki vụng về đến mức không ai buồn cập nhật. BookStack là wiki tự host hiếm hoi mà mọi người thực sự dùng. Nội dung được xếp trên kệ, trong sách, chương và trang — một cấu trúc ai cũng hiểu mà không cần đào tạo. Và nó hầu như không cần máy chủ.

Vì sao chọn BookStack

• Cấu trúc rõ ràng. Sách và chương thay cho một đống trang phẳng.
• Soạn thảo không làm ai sợ. Trình soạn thảo WYSIWYG mặc định, Markdown cho ai thích.
• Phân quyền thực thụ. Vai trò theo kệ, sách hoặc trang — giữ tài liệu nhân sự tránh xa người làm thuê ngoài.
• Đăng nhập của công ty. LDAP, SAML2 và OpenID Connect có sẵn.
• Dữ liệu của bạn. Mọi thứ nằm trong một cơ sở dữ liệu MariaDB và một thư mục trên máy chủ của bạn.

Nó không phải công cụ cho mọi việc. Tài liệu dành cho lập trình viên cần thay đổi cùng code nên nằm trong kho mã, không phải trong wiki.

Cần những gì

BookStack rất nhẹ. Với hầu hết các nhóm, Micro-IP — 1 vCPU, 2 GB, $10 mỗi tháng — là thừa đủ. IP riêng là thứ giúp đồng nghiệp truy cập qua HTTPS trên tên miền của bạn. Ổ đĩa tăng theo ảnh chụp màn hình và PDF được tải lên, không theo số trang.

Cài đặt bằng Docker Compose

Chúng ta sẽ dùng các image phổ biến của LinuxServer.io. Trước tiên tạo khóa ứng dụng:

docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey

Sao chép giá trị base64:... được in ra. Sau đó tạo docker-compose.yml:

services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    environment:
      - PUID=1000
      - PGID=1000
      - APP_URL=https://wiki.example.com
      - APP_KEY=base64:paste-your-key-here
      - DB_HOST=db
      - DB_PORT=3306
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack
      - DB_PASSWORD=change-me
    volumes:
      - ./bookstack:/config
    ports:
      - 127.0.0.1:6875:80
    depends_on:
      - db
    restart: unless-stopped
  db:
    image: lscr.io/linuxserver/mariadb:latest
    environment:
      - PUID=1000
      - PGID=1000
      - MYSQL_ROOT_PASSWORD=change-me-too
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=change-me
    volumes:
      - ./db:/config
    restart: unless-stopped

docker compose up -d
docker compose logs -f bookstack

APP_URL phải khớp với địa chỉ mọi người sẽ dùng, kể cả https://. Đặt sai thì ảnh và liên kết hỏng theo những cách kỳ lạ. Tìm hiểu thêm về Compose trong hướng dẫn triển khai stack của chúng tôi.

HTTPS và lần đăng nhập đầu

Trỏ một tên miền phụ về máy chủ (cách làm), đặt nginx trước 127.0.0.1:6875 và thêm chứng chỉ bằng certbot — hướng dẫn reverse proxy dẫn từng bước.

Sau đó đăng nhập bằng tài khoản mặc định: admin@admin.com / password. Đổi email và mật khẩu ngay, trước khi chia sẻ đường link. Những người khác nhận tài khoản riêng hoặc đăng nhập qua nhà cung cấp định danh của bạn.

Sao lưu

Hai thứ cần bảo vệ: cơ sở dữ liệu và các tệp tải lên trong ./bookstack. Một tác vụ chạy hằng đêm như thế này lo phần cơ sở dữ liệu:

docker compose exec -T db mysqldump -u bookstack -pchange-me bookstack > /var/backups/bookstack.sql

Sau đó sao lưu /var/backups và thư mục compose ra ngoài máy chủ — đúng những gì hướng dẫn restic của chúng tôi làm. Managed Backups bổ sung thêm điểm khôi phục hằng ngày cho toàn bộ máy chủ.

Bảo trì

Cập nhật chỉ là docker compose pull && docker compose up -d. BookStack tự chạy migration cơ sở dữ liệu khi khởi động. Đọc ghi chú phát hành trước các phiên bản lớn; chúng ngắn gọn và rõ ràng.

Nếu nhóm bạn cũng muốn một nơi cho ticket và code, một máy chủ Git tự host đặt cạnh nó rất hợp, trên cùng loại gói.