-
BookStack으로 책 만들기, '햄초보 가이드북'(아마추어 무선 온라인 안내서) 제작과정BookStack 2023. 4. 19. 00:48
이번에 "햄초보 가이드북"을 작성하면서 사용한 BookStack이라는 솔루션에 대해 소개합니다.
BookStack은 간단히 말해 책 형태로 관리되는 설치형 wiki입니다.
저는 온라인으로 작성하기 위해 어떤 도구를 사용할까 생각하다가 BookStack을 선택했습니다.
그 이유는 기존에 wiki형식이나 블로그 형식에는 장단점이 있기 때문입니다.wiki는 하이퍼 링크와 markdown문법을 지원하지만, 따로 목차가 마련되지 않는 이상 일목요연하게 정리된 내용을 보기에는 어려움이 있습니다.
블로그는 카테고리라는 항목을 이용하면 나름 순차적인 내용을 담을 수 있지만 책처럼 정보의 연결된 구성을 이어나가기 어려움이 있습니다.BookStack은 이러한 단점을 보완할 수 있는 책 형태의 wiki라고 할 수 있습니다.
국내에 알려진 지는 제법 되었지만, 아는 사람만 쓰는 도구같은 느낌입니다.
저는 책을 쓰면서 이 도구를 사용하면 제법 괜찮은 결과물을 만들어낼 수 있겠다 생각했습니다.기존 wiki와 다른 점은 책장-책-챕터-문서 형태의 위계를 가지고 구성되기에 문서의 구조와 목차를 확인하기 쉬운 장점을 가지고 있습니다. 마치 책을 써내려가듯이 정보를 취합하고 엮을 수 있습니다. 게다가 책 안에 쓰이는 왠만한 다이어그램을 자체 저작도구인 diagrams.net을 사용해서 쉽게 그릴 수 있습니다.
먼저 BookStack에 대한 이해는 BookStack 홈페이지(https://www.bookstackapp.com)를 통해서 했습니다.
앞서도 말했지만 BookStack의 몇가지 특징을 나열하면, 장점은 아래와 같습니다.
WYSIWYG 에디터나 markdown에디터를 선택해서 사용할 수 있으며,
diagrams.net을 내장시켜서 글을 작성하다가 얼마든지 도표나 다이어그램을 넣을 수 있습니다.
책꽂이-책-챕터-문서 형태로 위계구조를 이루며 챕터-문서는 순서를 얼마든지 바꿀 수 있습니다. 따라서 처음에 목차를 정하고 써내려가는 글 뿐만 아니라 쓰다가 문서에서 챕터(장)으로 올리고 싶은 경우, 또는 문서 자체를 가장 앞이나 중간 또는 뒤에 끼워넣는게 가능합니다.
전체 내용을 로그인 없이 공개할 수 있고, 일부 내용만 공개하고 나머지 내용은 로그인 해야 볼 수 있게도 만들 수 있습니다.
문서 앞 헤더에 들어갈 내용(CSS 스타일 등)을 만들어 적용할 수 있습니다.
이 외에도 WYSIWYG 에디터는 기본적인 기능들인 도표, 동영상, 이미지 삽입(파일올리기, 이미지 copy & paste지원), 링크기능, 코드블럭 삽입, 접철블럭 삽입 등을 제공합니다.
단점은 편집시 글꼴선택을 지원하지 않는다는 점, 백업이 프로그램화 되지 않아서 SSH로 접속해서 명령어로 처리해야 한다는 점, 멀티 BookStack을 만들려면 손이 좀 간다는 점 등입니다.온라인으로 내용을 만들자니 서버를 구성하고, 도메인(hamchobo.com)을 구입하였습니다.
그리고 서버에는 도커를 올리고 컨테이너 형태로 배포되는 BookStack을 사용하기로 했습니다.
BookStack 홈페이지에 따르면 BookStack 컨테이너에는 크게 2가지 배포본이 있는데, 저는 linuxserver 배포본을 사용했습니다.
설치를 마친 후 도커로 들어가서 위의 BookStack 컨테이너 배포 페이지에 나온 설치법 대로 몇가지 셋팅을 했습니다.
셋팅과정에 대해 간단히 설명하면 아래와 같습니다.
BookStack을 사용하려면 BookStack을 담고 있는 bookstack 컨테이너와 DB를 담고 있는 bookstack_db 컨테이너 2개가 설치해야 합니다. 이때 bookstack_db 컨테이너는 mariadb를 사용하면 됩니다.
https://hub.docker.com/r/linuxserver/bookstack
https://hub.docker.com/r/linuxserver/mariadb설치를 위해 docker-compose.yml 파일을 작성해줍니다.
version: "2"
services:
bookstack:
image: lscr.io/linuxserver/bookstack
container_name: bookstack
environment:
- PUID=1000
- PGID=1000
- APP_URL=<bookstack의 URL을 적어줍니다.>
- DB_HOST=bookstack_db
- DB_PORT=3306
- DB_USER=bookstack
- DB_PASS=<yourdbpass>
- DB_DATABASE=bookstackapp
volumes:
- /path/to/data:/config
ports:
- 6875:80
restart: unless-stopped
depends_on:
- bookstack_db
bookstack_db:
image: lscr.io/linuxserver/mariadb
container_name: bookstack_db
environment:
- PUID=1000
- PGID=1000
- MYSQL_ROOT_PASSWORD=<yourdbpass>
- TZ=Europe/London
- MYSQL_DATABASE=bookstackapp
- MYSQL_USER=bookstack
- MYSQL_PASSWORD=<yourdbpass>
volumes:
- /path/to/data:/config
restart: unless-stoppedcontainer name에는 BookStack를 지칭할 컨테이너 이름을 붙여주면 됩니다.
셋팅시 한 가지 중요한 점은 "APP_URL="이란 항목이 있는데, 여기에 BookStack의 URL에 해당하는 URL을 적어주면 되는데, http로 접속하더라도 https로 포워딩 되도록 만들었다면 https로 시작하는 주소를 적어줘야 합니다. 예) APP_URL=https://www.hamchobo.com
DB_HOST에는 BookStack에서 사용할 DB 컨테이너 이름을 써줍니다.
DB port는 3306을 기본으로 쓰는데, 이 포트를 다른 프로그램이 점유하고 있다면 포트를 다른 번호로 지정해주면 됩니다.
DB에서 사용할 user와 password를 지정해줍니다.
컨테이너를 만들 때 보면 서버의 /docker/bookstack/data와 BookStack 컨테이너의 /config가 볼륨연결형태로 연결됨을 알 수 있습니다.
나머지 DB 컨테이너에 대한 설정도 해줍니다.
MYSQL root password를 지정하고, TZ은 "TZ=Asia/Seoul"로 적어줍니다.
MYSQL user와 passowrd도 지정해줍니다.
그런 다음 docker-compose.yml로 저장한 뒤, 해당 파일을 서버에 올리고, 해당 디렉토리에서 docker-compose up -d 명령으로 설치하면 됩니다.
그리고 사용하는 도메인에 대해 https를 사용하기 위한 인증서 등을 발급 받고, 만약 공유기를 사용한다면 사용하는 포트(443, 80)들에 대한 공유기 포트포워딩 처리도 해줘야 합니다.
서버 내부적으로 역방향 프록시(reverse proxy)도 설정해서 http(80 port)로 들어오는 것에는 http://localhost:6875로, https(443 port)로 들어오는 것도 http://localhost:6875로 설정합니다.
이제 로그인을 하면 아래 같은 화면이 뜹니다. 초기 메일주소는 admin@admin.com 이고, 암호는 password 입니다.
로그인 한 뒤 설정으로 들어가서 기본적인 셋팅을 해줍니다. 우측상단을 사용자 부분을 클릭해서 "프로필 바꾸기"로 들어간 뒤 아래쪽의 항목 중 언어를 "한국어"로 바꾸고 저장하면 한글로 메뉴가 바뀝니다. 여기서 패스워드도 바꿔줍니다.
사이트를 전체공개 할거면 아래처럼 설정 > 보안 > 사이트 공개를 선택하면 됩니다.
책을 하나 만든 뒤, 아래처럼 대충 책의 목차를 잡고, 글을 써 내려가기 시작했습니다.
책을 마무리하고 제목은 "햄초보 가이드북"으로 했습니다.
저술기간은 3월 22일부터 4월 11일까지 하였고 오류사항을 고쳐 4월 12일 발간하게 되었습니다.
그렇게 하나의 아이(?)가 세상에 태어나게 됐습니다.이렇게 구축된 "햄초보 가이드북"은 아래 링크(햄초보닷컴)를 통해 볼 수 있습니다.
https://www.hamchobo.com이용방법은 아래와 같습니다.
①"햄초보 가이드북 보러가기"를 누릅니다.
② 혹시, 들어갔는데 "햄초보 가이드북" 화면이 안 뜨면, 오른쪽 위 메뉴에서 "책"을 선택하면 됩니다.추가로 BookStack관련하여 몇가지 팁을 말씀드립니다.
팁1. 전체공개상태에서 특정 책만 숨기고 싶을 경우
해당 책을 선택해서 들어간 뒤 왼편의 권한을 누릅니다.
그 다음 inherit defaults에 체크를 꺼주고, "권한저장" 버튼을 눌러 저장합니다. 그러면 BookStack이 "사이트 공개"로 전체 내용을 공개해도 해당 책은 로그인 하지 않은 사람들에게는 보이지 않게 됩니다. 즉, 공개할 내용과 자신만이 편집하고 보관할 책을 분리해서 사용할 수 있게 됩니다.팁2. PDF 출력시 한글과 이모지(Emoji) 폰트가 안깨지게 하는 법
BookStack을 설치한 뒤 그대로 사용하면, 책 내용을 "파일로 받기" > "PDF 파일"로 내보낼 경우 한글이 모두 깨져서 출력됩니다. 또한 이모지(Emoji) 문자를 사용할 경우도 마찬가지로 깨져서 나옵니다. 이런 문제에 대한 해결책은 아래와 같습니다.(BookStack에서는 dompdf 라는 모듈을 써서 PDF 문서로 변환하는데, 이 경우 문서가 제대로 안 만들어지고 한글이 깨지는 문제가 있습니다. 그래서 한글이 제대로 나오게 하려면 wkhtmltopdf라는 대체모듈을 사용해야 합니다.)
제가 깐 도커 이미지는 linuxserver에서 제공하는 BookStack이미지였습니다.
https://hub.docker.com/r/linuxserver/bookstack
참고로 나중에 언급할 것이지만 /config/www/.env 파일에 적어줄 wkhtmltopdf의 경로는 /usr/bin/wkhtmltopdf 입니다.
작업은 다음과 같습니다.
BookStack 설정 변경하기
BookStack 메뉴 "설정"을 누르고 왼편 "맞춤"을 누른 뒤 가장 아래로 가서 "헤드 작성"부분을 아래처럼 바꿔 주고 적용을 누릅니다.
<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>font는 Noto Sans KR을 사용했습니다. 원하면 다른 폰트를 적용할 수 있습니다(Google fonts에서 다운받아 깔고, 설정 변경하는 식으로).
글꼴 깔기
font-family로 설정한 글꼴(Noto Sans KR) 파일을 가져와 시스템의 기본글꼴 디렉토리(/usr/share/fonts)에 저장합니다 .
이 과정을 수행하기 위해 도커에 BookStack 컨테이너를 사용하는 경우에는 아래와 같이 합니다.
가. SSH로 서버에 접속합니다.
나. 도커의 BookStack컨테이너로 들어갑니다.
$ sudo docker exec -it bookstack bash
다. 시스템 기본글꼴 디렉토리(/usr/share/fonts)로 이동합니다.
$ cd /usr/share/fonts
Noto Sans KR 폰트를 다운받습니다.
$ curl -o notosanskr.zip https://fonts.google.com/download?family=Noto%20Sans%20KR
zip 파일 압축을 풀기 위해 upzip을 설치합니다.
$ apk add unzip
폰트파일 압축을 풉니다.
$ unzip -d /usr/share/fonts/notosanskr notosanskr.zip
$ fc-cache -fv
$ fc-list | grep noto 로 제대로 폰트가 설치됐는지 확인합니다.
이모지 문자(이모티콘) 깔기
이모지 문자를 사용하려면 아래처럼 Emoji One Color 폰트도 깔아줍니다. 이 폰트를 까는 이유는 다른 종류의 이모지 폰트들(예:font-noto-emoji)은 PDF변환시 모두 깨지기 때문입니다.
https://github.com/adobe-fonts/emojione-color.git 에서 Emoji One Color 폰트를 다운 받아 도커 컨테이너의 /usr/share/fonts에 올립니다.
폰트 다운로드 링크: emojione-color-master.zip DSM을 이용해 위에서 받은 emojione-color-master.zip을 도커 볼륨연결 폴더(/docker/config/)아래에 업로드하고,
SSH로 접속해서 BookStack 도커 컨테이너로 들어갑니다.
$ sudo docker exec -it bookstack bash
$ cd /config/
$ 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
WKHTMLTOPDF 설치
linuxserver의 도커가 포팅된 OS는 알파인 리눅스이므로 알파인 리눅스용 wkhtmltopdf를 설치해야 하는데, 이 파일 찾기가 어렵습니다.
그래서 일단 알파인 리눅스용 wkhtmltopdf만 담고 있는 도커 컨테이너(surnet/alpine-wkhtmltopdf)를 깐 뒤, 이 도커 컨테이너에 있는 파일을 BookStack 도커 컨테이너로 복사하는 방법을 써보겠습니다.
아래처럼 가져온 뒤 surnet/alpine-wkhtmltopdf 도커 컨테이너를 깔아줍니다.
도커를 실행은 안 시키고 그냥 설치만 할 것이므로 아래 그림처럼 "마법사 완료 후 이 컨테이너 실행"의 체크표시를 꺼줍니다.
가령 예를 들어 wkhtmltopdf1이라는 이름으로 설치를 하면 아래 같은 컨테이너가 만들어집니다. 실행시키면 에러가 나올 것입니다.(원래 WKHTMLTOPDF는 input주소, output파일을 지정하는 형태로 쓰는데 그냥 실행시키니 에러가 나오는 것입니다)
SSH 창에서 exit로 빠져나와서,
$ exit
아래처럼 하여 현재 디렉토리에 wkhtmltopdf 파일을 복사해 놓고,
$ docker cp wkhtmltopdf1:/bin/wkhtmltopdf .
이를 BookStack 도커 컨테이너의 /usr/bin/로 복사해줍니다(docker to docker 복사기능을 지원안하니 일단 내려받고 다시 옮기는 겁니다).
$ docker cp wkhtmltopdf bookstack:/usr/bin
참고로 복사가 끝나면 임시로 만들어놓은 wkhtmltopdf1 컨테이너는 지워도 됩니다.
이제 다시 BookStack 도커 컨테이너로 들어가서 /config/www아래의 .env 파일을 고쳐준다.
$ sudo docker exec -it bookstack bash
$ cd /config/www
$ vi .env
아래 내용을 추가한 뒤 Esc키를 누른 뒤 : 을 누르고 wq! 로 저장하고 빠져나옵니다.
WKHTMLTOPDF=/usr/bin/wkhtmltopdf
ALLOW_UNTRUSTED_SERVER_FETCHING=true그런 다음 wkhtmltopdf를 실행에 있어서 부수적으로 필요한 패키지들을 깔아줍니다.
$ apk add --update --no-cache libstdc++ libx11 glib libxrender libxext libintl libcrypto1.1 libssl1.1 ca-certificates fontconfig freetype ttf-dejavu ttf-droid ttf-freefont ttf-liberation
만약에 Microsoft제공 폰트들도 깔고 싶으면 아래 명령을 실행시킵니다(참고로 저는 설치 안했습니다).
$ 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에서 "파일로 받기" > "PDF 파일"을 눌러보면 제대로 동작할 것입니다.
그럼 이제까지 BookStack을 사용해서 온라인 책 만드는 법에 대해 설명했습니다.
BookStack은 온라인 책 뿐만 아니라 개인 wiki로 지식을 저장해놓거나 스크랩하는 용도로도 사용이 가능하므로 꽤 유용한 도구라고 생각합니다.
긴 글 읽어주셔서 감사합니다.