[Docker] BookStack: 오픈소스 문서 관리 플랫폼 (Docker Compose)

by


오픈소스 문서 관리 플랫폼인 BookStack에 대한 내용 및 docker compose로 환경을 구성한 내용을 정리합니다.

1. BookStack이란?

BookStack은 오픈소스 문서 관리 플랫폼으로, 기업이나 팀, 개인이 지식과 문서를 효과적으로 관리하고 공유할 수 있도록 설계된 도구입니다.

문서를 “책(Book)”, “챕터(Chapter)”, “페이지(Page)”의 구조로 구성하여 직관적으로 정리할 수 있으며, 간편한 사용자 인터페이스 덕분에 비전문가도 쉽게 사용할 수 있습니다.

일반적인 위키보다 더욱 구조적이면서 단순한 형식을 제공하여 문서 관리가 수월합니다.

2. 주요 특징

  1. 간편한 문서 편집
    BookStack은 WYSIWYG 에디터를 사용하여, 사용자가 서식이나 코드, 이미지를 쉽게 추가하고, 직관적으로 문서를 작성할 수 있도록 지원합니다. 마크다운도 지원해 개발자나 기술 문서 작성자에게도 친화적인 환경을 제공합니다.
  2. 계층적 구조
    “책” → “챕터” → “페이지”로 구성된 구조 덕분에 복잡한 내용을 쉽게 정리하고 찾아볼 수 있습니다. 각 계층을 태그를 통해 분류하여 관리 효율성을 높일 수 있습니다.
  3. 접근 권한 및 사용자 관리
    문서마다 접근 권한을 설정하여 읽기, 쓰기, 삭제 등의 권한을 제어할 수 있으며, LDAP 인증이나 OAuth를 통한 외부 인증도 지원해 편리하게 사용자 관리를 할 수 있습니다.
  4. 버전 관리 기능
    문서를 작성하거나 수정할 때마다 버전이 생성되며, 잘못된 수정이 있을 경우 이전 버전으로 손쉽게 복구할 수 있습니다.

3. BookStack 메뉴 및 기능

BookStack의 기본적인 메뉴와 기능은 다음과 같습니다.

1) 대시보드 (Dashboard)

  • 개요: 로그인 후 처음 표시되는 메인 화면입니다. 최근 작성되거나 수정된 문서와 자주 사용하는 문서를 빠르게 확인할 수 있습니다.
  • 기능: 최근 활동 표시, 즐겨찾기한 문서, 최근 수정된 문서, 빠른 검색창 제공.

2) 책 (Books)

  • 개요: 문서를 “책” 단위로 묶어 관리할 수 있으며, BookStack의 기본 단위가 됩니다.
  • 기능:
    • 책 생성 및 관리: 새 책 생성, 책 표지와 설명 작성.
    • 권한 설정: 책 단위로 특정 사용자나 그룹에만 접근 권한을 부여.
    • 내보내기: 책을 PDF, HTML, 마크다운 등 다양한 포맷으로 내보낼 수 있음.

3) 챕터 (Chapters)

  • 개요: 책 내부에서 챕터를 생성하여 내용을 세분화하고 더 잘 정리할 수 있습니다.
  • 기능:
    • 챕터 생성 및 편집: 책 안에 여러 개의 챕터를 생성하고 구성.
    • 페이지 추가: 챕터 내 페이지 추가 가능.
    • 재정렬: 챕터 내에서 페이지 순서를 손쉽게 변경 가능.

4) 페이지 (Pages)

  • 개요: 문서의 가장 작은 단위로, WYSIWYG 또는 마크다운 에디터를 사용해 문서를 작성합니다.
  • 기능:
    • 문서 작성 및 편집: 다양한 서식을 지원하며 이미지, 표, 코드 블록 등을 포함하여 문서 작성.
    • 버전 관리: 수정 시마다 버전이 생성되어 이전 버전 복구 가능.
    • 내보내기: 페이지 단위로 PDF, HTML, 마크다운 포맷으로 내보내거나 인쇄 가능.
    • 댓글 기능: 페이지에 댓글을 추가해 협업 가능.

5) 서반 (Bookshelf)

  • 개요: 여러 책을 그룹화하여 ‘서반’으로 관리할 수 있습니다.
  • 기능:
    • 서반 생성 및 관리: 프로젝트나 주제에 따라 관련 책들을 묶어 관리.
    • 권한 설정: 서반 단위로 접근 권한을 설정 가능.

6) 태그 (Tags)

  • 개요: 문서별로 태그를 추가해 문서 검색과 분류를 돕는 기능입니다.
  • 기능:
    • 태그 추가 및 관리: 문서에 다수의 태그를 추가하여 쉽게 분류하고 검색.
    • 태그 검색: 태그로 특정 주제나 키워드와 관련된 문서를 빠르게 검색 가능.

7) 검색 (Search)

  • 개요: 문서 제목, 내용, 태그 등을 검색하여 필요한 정보를 빠르게 찾을 수 있습니다.
  • 기능:
    • 전체 검색: 책, 챕터, 페이지, 첨부 파일 등 모든 콘텐츠에서 키워드 검색 가능.
    • 필터링: 검색 결과를 특정 날짜, 문서 유형 등에 따라 필터링 가능.

8) 사용자 및 역할 관리

  • 개요: 사용자와 역할을 관리하여 문서 접근과 편집 권한을 제어할 수 있습니다.
  • 기능:
    • 사용자 추가 및 관리: LDAP, SAML, OAuth와 같은 외부 인증을 지원하며, 기본 이메일과 비밀번호를 통한 인증도 가능.
    • 역할(Role) 설정: 관리자, 편집자, 조회자 등 역할별로 권한 설정 가능.
    • 팀 기능: 여러 사용자를 그룹화하여 쉽게 관리 가능.

9) 설정 (Settings)

  • 개요: BookStack의 전체 환경 설정을 관리할 수 있는 메뉴입니다.
  • 기능:
    • 사이트 설정: 사이트 제목, 언어, 시간대 등을 설정.
    • 메일 설정: 메일 서버 설정으로 사용자에게 알림 발송 가능.
    • 통합 설정: Google Analytics나 OAuth와 같은 외부 서비스 통합 가능.
    • 백업 및 복구: 데이터 백업 및 복구 기능을 통해 데이터를 안전하게 관리 가능.

10) 활동 로그 (Activity Logs)

  • 개요: 사용자의 모든 활동을 기록하는 기능으로, 누가 어떤 문서를 수정하거나 추가했는지 확인할 수 있습니다.
  • 기능:
    • 실시간 기록: 문서 작성, 수정, 삭제와 같은 활동 기록.
    • 활동 내역 조회: 활동 로그를 날짜, 사용자, 작업 유형에 따라 필터링.
    • 보안 감사: 보안 문제가 발생할 경우 원인 파악에 도움.

4. Docker Compose로 설치하기

Docker Compose를 사용하여 BookStack을 빠르게 설치하고 실행할 수 있습니다.

Docker Compose 파일 생성

프로젝트 디렉토리에서 docker-compose.yml 파일을 생성하고 아래 내용을 복사합니다.

version: '2'
services:
  mysql:
    image: mysql:8.3
    environment:
    - MYSQL_ROOT_PASSWORD=secret
    - MYSQL_DATABASE=bookstack
    - MYSQL_USER=bookstack
    - MYSQL_PASSWORD=secret
    volumes:
    - mysql-data:/var/lib/mysql

  bookstack:
    image: solidnerd/bookstack:24.10.1
    depends_on:
    - mysql
    environment:
    - DB_HOST=mysql:3306
    - DB_DATABASE=bookstack
    - DB_USERNAME=bookstack
    - DB_PASSWORD=secret
    #set the APP_ to the URL of bookstack without without a trailing slash APP_URL=https://example.com
    - APP_URL=http://localhost:8080
    # APP_KEY is used for encryption where needed, so needs to be persisted to
    # preserve decryption abilities.
    # Can run `php artisan key:generate` to generate a key
    - APP_KEY=SomeRandomStringWith32Characters
    volumes:
    - uploads:/var/www/bookstack/public/uploads
    - storage-uploads:/var/www/bookstack/storage/uploads
    ports:
    - "8080:8080"

volumes:
 mysql-data:
 uploads:
 storage-uploads:

Docker Compose 실행

터미널에서 다음 명령어를 실행하여 컨테이너를 시작합니다.

docker-compose up -d

완료되면 브라우저에서 http://localhost:8080으로 접속하여 BookStack에 접근할 수 있습니다.

5. 접속 테스트

최초 페이지

Admin 로그인

Admin 초기 계정은 github에서 확인 가능하고 아래와 같습니다.

ID : admin@admin.com
PW : password

Admin 접속 화면

마치며

BookStack은 직관적인 인터페이스와 체계적인 문서 관리 구조를 제공하여 누구나 쉽게 지식과 문서를 관리하고 공유할 수 있습니다.

특히, Docker Compose를 사용해 간편하게 설치할 수 있으므로 팀과 함께 체계적으로 문서를 관리하고자 할 때 유용한 솔루션입니다.

참고 문서

https://www.bookstackapp.com/docs/

https://www.bookstackapp.com/docs/admin/installation/#docker

https://github.com/solidnerd/docker-bookstack



Leave a Comment