이번에 데브코스에서 스터디를 진행하면서 깃북을 사용하려고 했는데 골치 아픈 문제가 있었습니다.
- 깃북으로 여러 명이 같이 편집을 하려면 유료 플랜이 필요한 점에서 부담이 있었습니다.
- 수정사항에 대해서 즉각적인 반영이 어려워 조금 귀찮은(?) 감이 없지 않아 있었습니다.
- 예를 들어 글 작성자가 아주 짧은 내용이나 오타를 수정해서 배포 중인 사이트에 적용하고 싶으면 담당자의 승인 과정이 필요합니다.
이런 이유로 다른 플랫폼이나 서비스를 찾고 있었고 그 중 BookStack을 발견했는데 상당히 괜찮은 거 같아서 글을 작성하게 됐습니다.
📚 BookStack
BookStack은 단순하고 자체 호스팅되며 사용하기 쉬운 플랫폼을 목표로 하는 무료 오픈 소스 위키 소프트웨어입니다.
✅ 장점
- 체계적인 구조: 책꽂이 → 책 → 챕터 → 문서 형태로 구성
- 마크다운 & WYSIWYG 지원: velog처럼 마크다운 작성 가능, WYSIWYG 에디터 제공
- 다이어그램 지원: draw.io 내장
- 권한 설정 가능: 로그인/비로그인 유저별 글 작성·보기·수정 권한 부여
- 글 내보내기(pdf, html, md, zip, txt) 가능 (추가 구현 필요)
❌ 단점
- 러닝 커브
- 서버 구축에 필요한 클라우드 관련 지식
- 편집 시 글꼴 선택을 지원하지 않음
- 백업 기능 미제공 (직접 구현 필요)
BookStack에 대해서는 간단히 소개하고 넘어가겠습니다.
자세한 내용은 아래 BookStack 사이트를 참고 해주세요!
또한 BookStack 개발자가 만든 데모 버전의 웹 페이지도 존재합니다.
👉 BookStack - Simple & Free Wiki Software
👉 BookStack - Demo(id: admin@admin.com, pw: password)
📋 준비물
BookStack을 서버에 구축하기 위해서는 다음과 같은 준비물이 필요합니다.
- 클라우드 관련 지식: AWS EC2, Docker, Nginx, Ubuntu
- AWS 프리티어 계정 및 EC2 인스턴스
- 도메인
AWS EC2 인스턴스 생성, 도메인 연결에 대한 방법은 다른 분들이 작성한 포스팅을 참고 부탁드립니다🙏
👉 AWS EC2 생성하기 => 4.7 단계 변경된 보안 그룹 확인까지만 참고해주시면 됩니다.
👉 AWS Route53을 이용한 도메인 연결
🐳 Docker 컨테이너를 이용한 Wiki 제작
1. Docker 설치
BookStack 홈페이지에 의하면 구축 방법이 여러가지가 있는데 저는 그 중에서 LinuxServer 배포판을 선택해 Wiki 사이트를 구축했습니다.
AWS EC2 터미널에 접속하고 아래의 명령어를 순서대로 입력해 Docker를 설치합니다.
$ sudo apt update
$ sudo apt install apt-transport-https ca-certificates curl software-properties-common -y
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
$ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
$ sudo apt-get install docker-ce docker-ce-cli containerd.io
$ sudo systemctl start docker
$ sudo systemctl enable docker
$ sudo usermod -aG docker $USER도커 설치 확인을 위해 다음의 명령어를 입력합니다.
$ docker version아래처럼 출력이 나오면 정상적으로 설치된 것입니다.
$ docker version
Client: Docker Engine - Community
Version: 28.0.0
API version: 1.48
Go version: go1.23.6
Git commit: f9ced58
Built: Wed Feb 19 22:11:04 2025
OS/Arch: linux/amd64
Context: default
Server: Docker Engine - Community
Engine:
Version: 28.0.0
API version: 1.48 (minimum version 1.24)
Go version: go1.23.6
Git commit: af898ab
Built: Wed Feb 19 22:11:04 2025
OS/Arch: linux/amd64
Experimental: false
containerd:
Version: 1.7.25
GitCommit: bcc810d6b9066471b0b6fa75f557a15a1cbf31bb
runc:
Version: 1.2.4
GitCommit: v1.2.4-0-g6c52b3f
docker-init:
Version: 0.19.0
GitCommit: de40ad02. docker-compose 설치
yml 파일 작성을 위해 docker-compose를 설치합니다.
$ sudo curl -L "https://github.com/docker/compose/releases/download/v2.18.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose다운로드한 docker-compose에 권한을 부여합니다.
$ sudo chmod +x /usr/local/bin/docker-compose설치 확인
$ docker-compose -v아래와 같이 출력이 되면 정상적으로 설치된 것입니다.
$ docker-compose -v
docker-compose version 1.29.2, build unknown3. docker-compose.yml 작성
docker-compose.yml 파일 작성을 위해 아래의 명령어를 입력합니다.
$ sudo mkdir my-wiki && cd my-wiki && sudo touch docker-compose.yml && sudo vi docker-compose.yml이후 docker-compose.yml 파일 내부에 아래의 내용을 복사 및 붙여넣기를 합니다.
services:
bookstack:
image: lscr.io/linuxserver/bookstack
container_name: bookstack-container
environment:
- PUID=1000
- PGID=1000
- TZ=Asia/Seoul
- APP_URL=<your_app_url>
- APP_KEY=<your_app_key>
- DB_HOST=mariadb
- DB_PORT=3306
- DB_DATABASE=<your_db_name>
- DB_USERNAME=<your_db_user>
- DB_PASSWORD=<your_db_password>
volumes:
- ./bookstack_app_data:/config
ports:
- 6875:80
restart: unless-stopped
mariadb:
image: lscr.io/linuxserver/mariadb:11.4.4
container_name: mariadb
environment:
- PUID=1000
- PGID=1000
- TZ=Asia/Seoul
- MYSQL_ROOT_PASSWORD=<your_db_password>
- MYSQL_DATABASE=<your_db_name>
- MYSQL_USER=<your_db_user>
- MYSQL_PASSWORD=<your_db_password>
volumes:
- ./bookstack_db_data:/config
restart: unless-stopped복사 및 붙여넣기 이후에는 필요한 환경변수를 작성합니다.
- APP_URL=<your_app_url>: 사용할 도메인 주소를 적어줍니다.
- 예시: APP_URL=https://www.your-domain.com
- APP_KEY=<your_app_key>: 사용할 앱 키값을 입력합니다.
- 키 값 생성은 아래 명령어를 통해 생성 가능합니다.APP_KEY=base64:XXX 여기에 생성된 키를 복사 및 붙여넣기 합니다.
- $ docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey
- DB_DATABASE=<your_db_name>: 데이터베이스 이름을 지정해주세요.
- DB_USERNAME=<your_db_user>: 데이터베이스 계정 이름을 적어줍니다.
- DB_PASSWORD=<your_db_password>: 데이터베이스 비밀번호를 입력합니다.
- MYSQL_ROOT_PASSWORD=<your_db_password>: 위에서 작성한 데이터 베이스 비밀번호와 동일하게 입력합니다.
- MYSQL_DATABASE=<your_db_name>: 동일한 데이터베이스 이름 입력
- MYSQL_USER=<your_db_user>: 동일한 데이터베이스 계정 이름 입력
- MYSQL_PASSWORD=<your_db_password>: 동일한 데이터베이스 비밀번호 입력
환경변수 작성을 모두 마쳤으면 esc키를 누르고 :wq를 입력하고 엔터를 눌러 편집기를 닫습니다.
이후에 다음의 명령어를 입력해서 BookStack을 설치하고 컨테이너를 가동시킵니다.
$ docker-compose up -d정상적으로 설치가 됐다면 아래와 같은 결과를 확인할 수 있습니다.
$ docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
2306a91c2261 lscr.io/linuxserver/mariadb:11.4.4 "/init" 24 hours ago Up 24 hours 3306/tcp mariadb
7d165fef5621 lscr.io/linuxserver/bookstack "/init" 24 hours ago Up 24 hours 443/tcp, 0.0.0.0:6875->80/tcp, [::]:6875->80/tcp cleancode-bookstack4. AWS Route 53 레코드 설정
Route 53 - 호스팅 영역으로 이동한 후 레코드 생성을 클릭합니다.
다음의 과정을 통해 레코드를 추가합니다.
- 레코드 이름: www
- 레코드 유형: A - IPv4 주소 및 일부 AWS 리소스로 트래픽 라우팅
- 값: 할당받은 EC2 탄력적 IP 주소
값 입력 후 레코드 생성 버튼을 클릭합니다.
다음과 같이 4개의 레코드가 존재하면 다음 단계로 진행하면 됩니다.
5. Nginx 설치
다음의 명령어로 Nginx를 설치합니다.
$ sudo apt install nginx -y설치 확인을 위해 다음 명령어를 입력합니다.
$ sudo systemctl status nginx다음과 같은 출력이 나오면 정상 설치된 것입니다.
$ sudo systemctl status nginx
● nginx.service - A high performance web server and a reverse proxy server
Loaded: loaded (/usr/lib/systemd/system/nginx.service; enabled; preset: enabled)
Active: active (running) since Wed 2025-02-26 21:26:51 KST; 21min ago
Docs: man:nginx(8)
Process: 21302 ExecStartPre=/usr/sbin/nginx -t -q -g daemon on; master_process on; (code=exited, status=0/SUCCESS)
Process: 21304 ExecStart=/usr/sbin/nginx -g daemon on; master_process on; (code=exited, status=0/SUCCESS)
Main PID: 21305 (nginx)
Tasks: 2 (limit: 1130)
Memory: 2.7M (peak: 3.0M)
CPU: 40ms
CGroup: /system.slice/nginx.service
├─21305 "nginx: master process /usr/sbin/nginx -g daemon on; master_process on;"
└─21306 "nginx: worker process"6. Let's Encrypt
무료 SSL 인증서를 설정하기 위해 관련 패키지를 설치합니다.
$ sudo apt install certbot python3-certbot-nginx -yLet's Encrypt를 통해 받은 무료 SSL 인증서의 경우 90일이 지나면 만료가 됩니다.
따라서 자동갱신을 위해서는 별도로 스크립트를 작성해 갱신을 자동화해야 합니다.
아래의 명령어를 입력해 편집기로 들어갑니다.
$ sudo crontab -e그 후 아래의 내용을 추가합니다.
0 3 * * * certbot renew --quiet && systemctl reload nginx- 매일 새벽 3시에 갱신을 시도하고 갱신 후 Nginx를 재시작합니다.
Ctrl + o -> Enter -> Ctrl + x 순서로 입력해서 텍스트 편집을 마칩니다.
7. Nginx 설정
Nginx 서버 블록을 설정하기 위해 다음의 명령어를 입력합니다.
$ sudo vi /etc/nginx/sites-available/default그 후 아래와 같이 파일을 작성합니다.
# HTTP로 들어오는 요청을 HTTPS로 리다이렉트하는 서버 블록
server {
listen 80;
server_name your-domain.com www.your-domain.com; # 도메인 입력
# 모든 요청을 HTTPS로 리다이렉트
return 301 https://$host$request_uri;
}
# HTTPS 요청을 처리하는 서버 블록
server {
listen 443 ssl;
server_name your-domain.com www.your-domain.com; # 도메인 입력
# SSL 인증서 설정
ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
# 웹 서버 설정
location / {
proxy_pass http://localhost:6875/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_cache_bypass $http_upgrade;
}
}server_name에 연결할 도메인 입력 후 esc키를 누르고 :wq를 작성한 후 엔터를 입력해 편집기를 닫습니다.
이후에 인증서 발급을 위해 다음의 명령어를 입력합니다.
$ sudo certbot --nginx -d your-domain.com -d www.your-domain.com인증서를 설정한 후 아래의 명령어를 입력해 Nginx를 재시작합니다.
sudo systemctl restart nginx여기까지 모두 정상적으로 진행이 됐다면 웹 브라우저에 본인의 도메인 주소를 입력했을 때
BookStack의 로그인 화면이 보이게 됩니다.
초기 관리자 메일 주소는 admin@admin.com이고 비밀번호는 password입니다.
⚙️ 간단한 설정 소개
1. 한글 설정
우측 상단 사용자 부분을 클릭하고 내 계정으로 들어갑니다.
Preferred Language에서 한국어를 선택하고 저장을 눌러 언어를 변경합니다.
2. 공개 엑세스 허용
우측 상단 설정을 클릭합니다.
공개 엑세스 허용 체크 박스에 체크를 하고 적용을 하면
로그인하지 않은 유저도 권한에 따라 콘텐츠에 접근이 가능합니다.
3. 어플리케이션 설정
설정 - 어플리케이션 설정 탭으로 이동합니다.
어플리케이션 이름: 사이트의 제목을 설정합니다.
기본 페이지 편집기: 문서를 작성할 때 사용되는 기본 편집기를 설정합니다.
어플리케이션 로고: 상단 바와 같은 영역에 표시되는 로고 이미지를 설정합니다.
어플리케이션 아이콘: favicon 이미지를 설정합니다.
🛠️ 트러블 슈팅
- 한글 및 이모지 PDF로 출력 시 깨지는 현상[TIL] - 2025.02.28