BookStack용 VPS: 셀프 호스팅 팀 위키

팀 문서는 보통 둘 중 하나로 죽습니다. 아무도 검색할 수 없는 채팅 스레드에 흩어지거나, 너무 불편해서 아무도 갱신하지 않는 위키에 묻히거나. BookStack은 사람들이 실제로 쓰는 드문 셀프 호스팅 위키입니다. 내용은 책장, 책, 장, 페이지에 정리되고, 누구나 교육 없이 이해하는 구조입니다. 게다가 서버도 거의 필요 없습니다.

왜 BookStack인가

• 분명한 구조. 평평한 페이지 더미 대신 책과 장.
• 아무도 겁먹지 않는 편집. 기본은 WYSIWYG 편집기, 원하는 사람은 Markdown.
• 제대로 된 권한. 책장, 책, 페이지별 역할로 인사 문서를 외부 협력자에게서 떼어 놓습니다.
• 회사 로그인. LDAP, SAML2, OpenID Connect가 기본 내장돼 있습니다.
• 내 데이터. 모든 게 MariaDB 데이터베이스와 서버의 폴더 하나에 있습니다.

모든 일에 맞는 도구는 아닙니다. 코드와 함께 바뀌어야 하는 개발 문서는 위키가 아니라 저장소에 둬야 합니다.

필요한 사양

BookStack은 가볍습니다. 대부분의 팀에는 Micro-IP — 1 vCPU, 2 GB, 월 $10 — 로 충분하고도 남습니다. 동료들이 내 도메인에 HTTPS로 접속할 수 있게 해 주는 게 전용 IP입니다. 디스크는 페이지 수가 아니라 업로드한 스크린숏과 PDF 때문에 늘어납니다.

Docker Compose로 설치하기

널리 쓰이는 LinuxServer.io 이미지를 사용합니다. 먼저 애플리케이션 키를 생성하세요.

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

출력된 base64:... 값을 복사한 뒤 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은 https://까지 포함해 사람들이 쓸 주소와 일치해야 합니다. 틀리면 이미지와 링크가 이상하게 깨집니다. Compose에 대해서는 스택 배포 가이드에 더 있습니다.

HTTPS와 첫 로그인

서브도메인을 서버로 연결하고(방법), 127.0.0.1:6875 앞에 nginx를 두고, certbot으로 인증서를 추가하세요. 리버스 프록시 가이드가 단계별로 안내합니다.

그다음 기본 계정 admin@admin.com / password로 로그인하세요. 링크를 공유하기 전에 이메일과 비밀번호를 바로 바꾸세요. 나머지 사람들은 각자 계정을 받거나 ID 공급자를 통해 로그인합니다.

백업

지켜야 할 건 두 가지, 데이터베이스와 ./bookstack 안의 업로드입니다. 이런 야간 작업이면 데이터베이스는 챙길 수 있습니다.

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

그다음 /var/backups와 compose 폴더를 서버 밖으로 백업하세요. restic 가이드가 정확히 그 일을 합니다. 여기에 Managed Backups로 서버 전체의 일일 복원 지점을 더할 수 있습니다.

운영

업데이트는 docker compose pull && docker compose up -d면 됩니다. BookStack은 시작할 때 데이터베이스 마이그레이션을 실행합니다. 메이저 버전 전에는 릴리스 노트를 읽으세요. 짧고 명확합니다.

팀에 티켓과 코드를 둘 곳도 필요하다면, 같은 종류의 요금제에 셀프 호스팅 Git 서버를 나란히 두면 잘 어울립니다.