홈랩 서비스가 열 개, 스무 개로 늘어나면 어떤 서비스가 어떤 포트를 쓰는지, 어디에 무슨 설정을 해뒀는지조차 기억나지 않는 시점이 와요. BookStack은 이런 파편화된 지식을 Shelves(책장) - Books(책) - Chapters(장) - Pages(페이지)라는 도서관식 계층 구조로 정리해주는 오픈소스 위키예요. 그렇다면 BookStack으로 셀프호스팅 위키/문서 관리를 어떻게 시작할 수 있을까요?
BookStack이란 무엇인가
BookStack은 일반적인 위키 소프트웨어와 달리 문서를 책장에 꽂힌 책처럼 계층적으로 정리하도록 설계된 셀프호스팅 지식베이스예요. 최상위에 Shelf(책장)가 있고, 그 안에 여러 Book(책)이 꽂히고, 각 Book은 다시 Chapter(장)로 나뉘며, 최종적으로 Page(페이지)가 실제 내용을 담아요. Confluence나 Notion처럼 자유도가 높은 구조 대신 이렇게 정해진 계층을 강제하기 때문에, 문서가 늘어나도 어디에 뭘 넣어야 할지 헷갈리지 않는다는 장점이 있어요. 이 구조 자체가 정리 규칙이 되어주는 셈이에요.
홈랩 문서화에 잘 맞는 이유
홈랩을 운영하다 보면 네트워크 구성도, 서비스별 포트 목록, 장애 발생 시 대응 절차(런북) 같은 문서가 자연스럽게 쌓이는데, BookStack의 계층 구조가 이런 정보를 나누기에 특히 잘 맞아요.
- Shelf 단위 대분류: “네트워크”, “미디어 서버”, “백업”처럼 큰 영역별로 책장을 나눠요.
- Book 단위 서비스 정리: 서비스 하나(예: Jellyfin, Vaultwarden)당 Book 하나를 만들어 설치 과정, 설정값, 트러블슈팅을 모아둬요.
- Chapter 단위 세부 주제: 설치, 백업, 업그레이드처럼 서비스 안에서도 성격이 다른 작업을 장으로 구분해요.
- Page 단위 실제 문서: 실제 명령어와 스크린샷이 들어가는 최소 단위예요.
네트워크 구성도를 이미지로 첨부하고, 서비스별 런북을 페이지로 남겨두면, 몇 달 뒤 같은 문제가 다시 생겼을 때 검색 한 번으로 예전 해결 과정을 그대로 찾아볼 수 있어요.
비밀번호는 BookStack이 아니라 전용 도구에
BookStack에 서비스 접속 정보를 정리하다 보면 비밀번호도 같이 적어두고 싶은 유혹이 생기는데, 이건 피하는 게 좋아요. BookStack은 문서 관리 도구지 암호화된 자격 증명 저장소가 아니기 때문에, 실제 비밀번호나 API 키는 Vaultwarden 같은 전용 비밀번호 관리자에 저장하고 BookStack 문서에는 “이 서비스의 자격 증명은 Vaultwarden의 어느 폴더에 있다”는 식의 참조만 남기는 방식이 안전해요. 문서와 비밀은 성격이 다른 자산이라, 애초에 저장 도구를 분리해두면 나중에 문서를 외부와 공유해야 할 때도 고민할 일이 줄어들어요.
WYSIWYG와 마크다운을 함께 쓰기
BookStack은 페이지마다 WYSIWYG 에디터와 마크다운 에디터 중 하나를 선택해서 작성할 수 있어요. 표나 이미지가 많이 들어가는 문서는 WYSIWYG로 마우스만으로 빠르게 편집하고, 명령어나 설정 파일 스니펫이 많은 기술 문서는 마크다운으로 작성해서 코드 블록을 깔끔하게 유지하는 식으로 섞어 쓸 수 있어요. 어느 에디터로 쓰든 이미지를 드래그 앤 드롭하면 자동으로 업로드되기 때문에, 네트워크 구성도나 에러 화면 스크린샷을 문서 중간에 바로 붙여넣을 수 있어요.
Docker Compose로 설치하기
BookStack은 MySQL 같은 데이터베이스가 필요한 PHP 애플리케이션이라, 앱 컨테이너와 데이터베이스 컨테이너를 함께 구성해요.
services:
bookstack:
image: lscr.io/linuxserver/bookstack:latest
environment:
- PUID=1000
- PGID=1000
- APP_URL=http://localhost:6875
- DB_HOST=bookstack_db
- DB_USER=bookstack
- DB_PASS=changeme
- DB_DATABASE=bookstackapp
ports:
- "6875:80"
depends_on:
- bookstack_db
volumes:
- ./bookstack/config:/config
bookstack_db:
image: lscr.io/linuxserver/mariadb:latest
environment:
- PUID=1000
- PGID=1000
- MYSQL_ROOT_PASSWORD=changeme
- MYSQL_DATABASE=bookstackapp
- MYSQL_USER=bookstack
- MYSQL_PASSWORD=changeme
volumes:
- ./bookstack/db:/configDB_PASS와 MYSQL_PASSWORD 값은 반드시 실제 환경에서는 강력한 값으로 바꿔야 해요. 예시에 남겨둔 changeme 그대로 운영하면 데이터베이스가 외부에 노출됐을 때 그대로 뚫릴 수 있어요.
권한 관리로 협업 범위 조절하기
여러 사람이 함께 홈랩을 운영하거나 일부 문서를 외부 협업자와 공유해야 할 때는 BookStack의 역할 기반 권한이 유용해요. Shelf, Book, Chapter, Page 각 단계마다 열람·편집 권한을 따로 지정할 수 있어서, 특정 Book만 골라 협업자에게 편집 권한을 주고 나머지 Book은 비공개로 유지하는 세밀한 조정이 가능해요. 가족 구성원에게는 읽기 권한만, 직접 관리하는 사람에게는 편집 권한을 주는 식으로 나누면 문서가 실수로 훼손될 위험도 줄어들어요.
결론
BookStack은 Shelves-Books-Chapters-Pages라는 명확한 계층 구조로 홈랩의 흩어진 지식을 하나의 위키에 모아주는 도구예요. 몇 달 전에 어떻게 설정했는지 기억이 가물가물할 때, 검색창에 서비스 이름만 입력하면 그때 남겨둔 런북이 그대로 나오는 경험은 한번 해보면 쉽게 포기하기 어려워요. 문서에 적을 비밀번호는 Vaultwarden에 따로 보관해서, 지식과 비밀을 각자 맞는 도구에 나눠 담아보세요.
자주 묻는 질문
Q1. BookStack에 서비스 비밀번호를 그대로 적어둬도 되나요?
아니요, BookStack은 문서 관리 도구일 뿐 암호화된 자격 증명 저장소가 아니라서 비밀번호나 API 키 원문을 페이지에 그대로 적는 건 권장하지 않아요. 실제 비밀번호는 [Vaultwarden](/blog/vaultwarden-self-hosted-password-manager) 같은 전용 비밀번호 관리자에 저장하고, BookStack에는 해당 항목의 위치나 접근 절차만 문서화하는 방식이 안전해요.
Q2. 마크다운으로만 작성해야 하나요?
아니요, BookStack은 WYSIWYG 에디터와 마크다운 에디터를 페이지별로 선택할 수 있어요. 표나 이미지를 많이 쓰는 페이지는 WYSIWYG로, 코드 스니펫이 많은 페이지는 마크다운으로 작성하는 식으로 섞어 쓸 수 있어요.
Q3. 권한을 세밀하게 나눠서 특정 문서만 공유할 수 있나요?
네, BookStack은 Shelf, Book, Chapter, Page 각 단계마다 역할 기반으로 열람·편집 권한을 따로 설정할 수 있어요. 특정 Book만 외부 협업자에게 공개하고 나머지는 비공개로 유지하는 것도 가능해요.
Q4. 위키 안에서 전체 문서를 검색할 수 있나요?
네, BookStack은 제목뿐 아니라 본문 내용까지 포함한 전체 텍스트 검색을 기본으로 지원해요. 태그를 붙여두면 태그 기반 필터링으로도 원하는 문서를 빠르게 찾을 수 있어요.
Q5. 이미지나 다이어그램도 문서에 바로 첨부할 수 있나요?
네, 에디터에 이미지를 드래그 앤 드롭하면 자동으로 업로드되고 본문에 삽입돼요. 네트워크 구성도나 스크린샷을 문서 안에 바로 넣을 수 있어서 별도 이미지 호스팅 없이도 문서를 완성할 수 있어요.
Q6. 다른 사람이 수정한 이력을 되돌릴 수 있나요?
네, BookStack은 페이지마다 수정 이력을 자동으로 저장해서 이전 버전으로 되돌리거나 변경 내용을 비교해볼 수 있어요. 여러 명이 함께 문서를 관리할 때 실수로 내용이 삭제돼도 복구할 수 있는 안전장치가 돼요.
관련 글
