Wiki Server : Bookstack

Bookstack 소개
사전준비
설치
환경설정

SMTP 설정
언어설정
Redis 설정
목록 형태
PDF 변환 한글 지원

SSL 인증서 오류 (기존 시놀로지 인증서 활용 방법)

Bookstack 소개

개인 Wiki를 운영할 수 있는 오픈소스 프로그램 입니다.

제가 운영하는 "DH Cloud Wiki"가 이 Bookstack으로 운영 되고 있습니다.

사전준비

Database 설치가 필요 합니다.

1. Database는 MariaDB를 이용하며, Synology Package 센터에 있는 MariaDB 10을 예제로 설명 합니다.

다른 DBMS가 이미 있다면 이 단계는 넘어가시면 됩니다.

2. Synology Package 센터에서 MariaDB 10 앱을 설치 후 "TCP/IP 연결 활성화"를 체크하고, 포트는 3306으로 설정 합니다.

2. MariaDB에 Nextcloud Database 및 사용자 생성을 위해 Synology Package 센터에 있는 phpMyAdmin을 설치 합니다.

1) "데이터베이스 > 새로운"에서 "bookstack"로 신규 Database를 생성 합니다.

2) "bookstack" Database를 선택하고 우측 상단의 "권한"을 선택 합니다.

3) 아래 예제와 같이 사용자명에 "bookstack"를 입력하고 암호와 재입력란에 사용하고자하는 암호를 입력 합니다.

그런 후 전체적 권한에 "모두 체크"를 선택하여, 사용자가 Database의 모든 권한을 사용할 수 있게 설정 합니다.

설치

볼륨 Mapping을 위한 "/volume1/docker/bookstack/config" 디렉토리와 "/volume1/docker/bookstack/fonts" 생성 합니다.

mkdir /volume1/docker/bookstack/config

# weasyprint를 이용한 한글 PDF 출력 옵션을 사용할 경우 아래를 추가로 진행 합니다.
mkdir /volume1/docker/bookstack/fonts

Docker 설치에 앞서 자신의 계정에 대한 "PUID"와 "PGID"를 확인 합니다.

id 계정명

여기서 uid값 (PUID)과 gid값 (PGID)를 기록해 둡니다. 제 경우 uid=1026, gid=100 입니다.

"docker-compose.yml" 파일을 아래와 같이 생성 합니다.

version: "2"
services:
  bookstack:
    image: lscr.io/linuxserver/bookstack
    container_name: bookstack
    environment:
      - PUID=1026
      - PGID=100
      - APP_URL="도메인" # 예 : "http://...."와 같은 실제 사용하실 도메인을 넣어줍니다.
      - TZ="Asia/Seoul"
      - DB_HOST="DB_IP" # 예 : "192.168.1.200"
      - DB_PORT=DB_PORT # 예 : 3306
      - DB_USER="bookstack"
      - DB_PASS="DB비번"
      - DB_DATABASE="bookstack"
    volumes:
      - '/volume1/docker/bookstack/config:/config'
      # weasyprint를 이용한 한글 PDF 출력 옵션을 사용할 경우 아래를 추가로 진행 합니다. 
      - '/volume1/docker/bookstack/fonts:/usr/share/fonts'
    ports:
      - '6875:80' # APP_URL의 연결이 https일 경우 80을 443으로 수정해 주셔야 합니다.
    restart: unless-stopped

아래 명령으로 Docker를 실행 합니다.

docker-compose up -d

접속은 "IP:6875" 입니다. 초기 계정은 아래와 같으며, 최초 로그인 후 수정해 주시면 됩니다.

ID : admin@admin.com
PW : password

환경설정

SMTP 설정

사용자 생성 및 이후 원활한 사용을 위해서는 반드시 smtp 설정이 필요 합니다.

설치된 Docker와 Mapping된 아래 파일을 열어 ".env" 파일 (config/www/.env)을 수정해 줍니다.

# Mail system to use
# Can be 'smtp' or 'sendmail'
MAIL_DRIVER=smtp

# Mail sender details
MAIL_FROM_NAME="메일발송자"
MAIL_FROM=이메일주소

# SMTP mail options
# These settings can be checked using the "Send a Test Email"
# feature found in the "Settings > Maintenance" area of the system.
MAIL_HOST=smtp.naver.com
MAIL_PORT=465
MAIL_USERNAME=smtp계정아이디
MAIL_PASSWORD=smtp계정비번
MAIL_ENCRYPTION=tls

위 예제는 네이버 smtp 이며 사용자 환경에 맞게 수정해 주시면 됩니다.

환경설정

언어설정

기본언어를 한국어로 설정하는 방법입니다.

설치된 Docker와 Mapping된 아래 파일을 열어 ".env" 파일 (config/www/.env)을 추가해 줍니다.

# Sets application language to Korean
APP_LANG=ko
APP_AUTO_LANG_PUBLIC=false

환경설정

Redis 설정

먼저 Redis가 설치되어 있다고 가정합니다. (Redis 설치 문서를 참고 하세요)

Redis의 Network와 bookstack의 네트워크를 같은 네트워크로 연결해 줍니다.

아래 예제는 "home_network"라는 곳에 연결해 주었습니다.

["home_network" 생성]

docker network create home_network

["home_network"와 "bookstack" 네트워크 연결]

docker network connect home_network bookstack

설치된 Docker와 Mapping된 아래 파일을 열어 ".env" 파일 (config/www/.env)을 추가해 줍니다.

# Set both the cache and session to use Redis
CACHE_DRIVER=redis
SESSION_DRIVER=redis

# Example of using a single local Redis server
REDIS_SERVERS=Redis_IP:6379:0

Redis_IP는 Portainer의 Network에서 확인 가능합니다. Redis가 사용 중인 IP 값 또는 IP가 변동될 시 "Host Name"을 넣어주시면 됩니다.

REDIS_SERVERS=redis:6379:0

환경설정

목록 형태

Grid 형식과 List 형식 두 가지중 아래와 같이 선택 가능합니다.

설치된 Docker와 Mapping된 아래 파일을 열어 ".env" 파일 (config/www/.env)을 추가해 줍니다.

[그리드 형식]

APP_VIEWS_BOOKS=grid

[리스트 형식]

APP_VIEWS_BOOKS=list

환경설정

PDF 변환 한글 지원

먼저 Bookstack "설정 > 맞춤 > 헤드 작성"에 아래 코드를 넣어 줍니다. (Google 한글 웹폰트를 사용하기 위함)

<link href=" https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@100;300;400;500;700;900&display=swap " rel="stylesheet">
<style>
  body {
  text-rendering: geometricPrecision;
  }  
  body, button, input, select, label, textarea {
font-family: "Noto Sans KR";
  }
</style>

Portainer를 통해 Bookstack 콘솔로 진입하시던가 아니면 아래와 같이 ssh로 Bookstack 콘솔로 진입 합니다.

sudo docker exec -it bookstack bash

Font 디렉토리로 이동 합니다.

cd /usr/share/fonts

notosanskr 디렉토리를 생성하고 이동합니다.

mkdir notosanskr
cd notosanskr

Google "Noto Sans KR" 폰트를 다운받습니다.

curl -o Noto_Sans_KR.zip https://fonts.google.com/download?family=Noto%20Sans%20KR (동작 X)

wget https://gqm.trigem.com/Share/font/Noto_Sans_KR.zip

압축을 해제하기 위해 unzip을 설치해 줍니다.

apk add --no-cache unzip

압축을 해제하고 원본 zip파일을 삭제합니다.

unzip Noto_Sans_KR.zip -d /usr/share/fonts/notosanskr/
rm Noto_Sans_KR.zip

폰트를 설치 합니다.

fc-cache -fv

폰트 설치를 확인합니다.

fc-list | grep noto

"bookstack/config/www/" 밑에 있는 ".env" 파일을 열어 아래 내용을 추가해 줍니다.

EXPORT_PDF_COMMAND="weasyprint {input_html_path} {output_pdf_path}"

"production.ERROR: PDF Export via command failed due to timeout at 15 second(s)"라는 오류가 발생시 아래 timeout 시간을 추가해 줍니다.

EXPORT_PDF_COMMAND_TIMEOUT=120

weasyprint 사용을 위해서는 weasyprint apk 설치가 필요 합니다.

기본적으로 docker 콘솔에 접속해 apk를 설치해 주면 되는데 docker image가 업데이트 될 경우 설치된 apk가 삭제 됩니다.

sudo docker exec -it bookstack bash

apk add --no-cache weasyprint

docker 컨테이너가 시작될 때 weasyprint apk 설치 유무를 확인 후 없을 시 자동으로 설치를 진행하는 절차를 성명 드립니다.

"/volume1/docker/bookstack/config/weasyprint_apk.sh"에 아래 sh스크립트를 작성 합니다.

#!/bin/sh

# Check if weasyprint is installed
if ! apk info | grep -q weasyprint; then
    echo "WeasyPrint is not installed. Installing now..."
    # Install weasyprint without cache
    apk add --no-cache weasyprint
else
    echo "WeasyPrint is already installed."
fi

# Keep the container running
tail -f /dev/null

docker 콘솔에 접속하여 작성된 sh에 대한 권한을 부여해 줍니다.

sudo docker exec -it bookstack bash

chmod +x /config/weasyprint_apk.sh

docker 컨테이터의 cmd에 "/config/weasyprint.sh"를 입력해 주고, "Deploy the container"를 실행 합니다.

----------------------------------------------------------------------------------------------------

추가 문자 폰트 설치 (옵션)

----------------------------------------------------------------------------------------------------

1. 이모지 폰트 설치

아래 github (https://github.com/adobe-fonts/emojione-color)에서 폰트를 로컬에 다운로드 합니다.

https://github.com/adobe-fonts/emojione-color/archive/refs/heads/master.zip

다운로드 받은 zip 파일을 bookstack의 "config" 디렉토리에 업로드 합니다.

Bookstack 콜솔로 진입합니다.

sudo docker exec -it bookstack bash

"config"로 이동 합니다.

cd /config/

업로드한 zip 파일을 폰트 디렉토리로 이동합니다.

mv emojione-color-master.zip /usr/share/fonts

폰트 디렉토리로 이동합니다.

cd /usr/share/fonts

압축을 해제 합니다.

unzip -d emojionecolor emojione-color-master.zip

폰트를 설치 합니다.

fc-cache -fv

설치를 확인 합니다.

fc-list | grep emojione

Bookstack 콜솔에 접속 중이라면 아래 명령어로 빠져나갑니다.

exit

2. MS 폰트 설치

Bookstack 콘솔로 진입합니다.

sudo docker exec -it bookstack bash

"config"로 이동 합니다.

cd /config/www

MS 폰트를 설치해 줍니다. (Option 사항 입니다.)

apk add --no-cache --virtual .build-deps msttcorefonts-installer 
update-ms-fonts  
fc-cache -f  
rm -rf /tmp/*  
apk del .build-deps

마지막으로 폰트 리스트를 업데이해 해줍니다.

fc-cache -fv

Bookstack 컨테이너를 재실행해 줍니다.

[주의]
1. 도커 이미지가 업데이트 되면 위 설정은 모두 초기화 됩니다. Watchtower를 이용 중이라면 예외 Lable 처리를 하셔야 합니다.
(https://wiki.dhcloud.me/books/docker-updater-watchtower/page/94f6d)
2. Watchtower를 통한 자동 이미지 업데이트를 사용하신다면 위 본문에 설명명 "weasyprint_apk.sh" CMD를 설정해 주시기 바랍니다.

SSL 인증서 오류 (기존 시놀로지 인증서 활용 방법)

SSL 관련 오류를 해결하기 위해서는 SSL 인증서를 설치해 주셔야 합니다.

본 해결 방법은 시놀로지를 사용할 경우 간단히 시놀로지의 인증서를 빼내서 Bookstack에 적용하는 방법입니다.

1. "시놀로지 제어판 > 보안 > 인증서" 항목에서 기존 보유한 인증서를 선택 후 "인증서 내보내기"를 실행 합니다. (PC로 다운로드)

2. 압축을 풀고 이 중에서 사용할 인증서는 "cert.pem"와 "privkey.pem" 입니다.

3. Bookstack에 적용
1) "docker/bookstack/config/keys" 밑에 "cert.crt"와 "cert.key" 두개의 파일이 있습니다.
2) "cert.crt"을 열어 앞서 다운로드 받은 "cert.pem" 파일의 내용을 메모장을 열어 복사하고 붙여 줍니다.
3) "cert.key"을 열어 앞서 다운로드 받은 "privkey.pem" 파일의 내용을 메모장을 열어 복사하고 붙여 줍니다.

4. Docker Container를 재시작 합니다.