BookStack 간단 매뉴얼

제가 "편리하다!"고 느껴서 자주 쓰는 BookStackApp의 영어 설명을 한글로 번역해 둔 것입니다. 

설치

설치

요구사양

BookStack은 생각보다 요구사양이 복잡하지 않습니다. 

 

 

설치

사전설치

본 문서는 FreeBSD에 대응하여 설명합니다. 

PHP 설치

2024년 01월 14일 기준 8.3.1이 포트에 올라와 있습니다. 다음 명령으로 가장 기본 프로그램을 설치합니다. 

sudo pkg install php83-8.3.1

설치 후에 추가 확장기능을 설치합니다.

# OpenSSL extension은 자동설치되기 때문에 따로 설치하지 않아도 됩니다.

sudo pkg install php83-dom-8.3.1 php83-pdo-8.3.1 php83-mbstring-8.3.1 php83-iconv-8.3.1 php83-gd-8.3.1 php83-mysqli-8.3.1 php83-simplexml-8.3.1 php83-tokenizer-8.3.1

sudo pkg install php83-ldap-8.3.1

위의 내용을 보시면 아시겠지만 기본적인 이름 형태가 정해져 있습니다. 나중에 다른 버전을 설치하실때도 참고하세요. 

 

$ git clone {url} {설정할 폴더이름}

설치

설치

Shared Hosting

북스택은 현재 공유 PHP 호스팅을 지원하지 않습니다. 공유 호스팅 제공업체마다 차이가 너무 많고 현재 설치 프로세스를 지원하기에는 제한 사항이 너무 많지만 향후 이를 더 쉽게 만들고 싶습니다. 호스팅 제공업체의 'Laravel 설치 가이드'를 검색해 보시면 프로세스가 비슷할 것입니다. 애플리케이션 소스 파일을 수정하거나 큰 규모의 해결 방법을 적용하면 보안 또는 안정성 문제가 발생할 수 있으므로 주의하세요.

 

Manual Installation

설치하기 전에 위의 요구 사항이 충족되는지 확인하세요.

이 프로젝트는 현재 업데이트를 제공하기 위한 안정적인 채널로 BookStack GitHub 리포지토리의 release 브랜치를 사용하고 있습니다. 설치는 현재 다소 복잡하며 향후 릴리스에서 더 간단하게 개선될 예정입니다. PHP 또는 Laravel 경험이 있다면 더 쉽게 설치할 수 있습니다.

1. BookStack GitHub 리포지토리의 릴리스 브랜치를 폴더에 복제합니다.

$ git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch

2. cd를 써서 애플리케이션 폴더로 이동하고 composer install --no-dev를 실행합니다.

3. .env.example 파일을 .env로 복사하고 고유한 데이터베이스 및 메일 세부 정보를 입력합니다.

4. storage, bootstrap/cache 및 public/uploads 폴더가 웹 서버에서 쓰기 가능한 폴더인지 확인합니다(자세한 내용은 여기를 참조하세요).

5. 애플리케이션 루트에서 php artisan key:generate를 실행하여 고유한 애플리케이션 키를 생성합니다.

6. Apache를 사용하지 않거나 .htaccess 파일을 비활성화하는 경우 아래와 같이 URL 재작성 규칙을 만들어야 합니다.
    서버의 웹 루트가 BookStack 공용 폴더를 가리키도록 설정합니다. 이 작업은 Nginx의 루트 설정 또는 Apache의 DocumentRoot 설정으로 수행됩니다.
    PHP 아티산 마이그레이션을 실행하여 데이터베이스를 업데이트합니다.
    완료! 이제 기본 관리자 세부 정보 admin@admin.com 에 비밀번호를 사용하여 로그인할 수 있습니다. 처음 로그인한 후에는 이러한 세부 정보를 즉시 변경해야 합니다.

자잘한 설정

사용하면서 바꾸게 되는 자잘한 설정

자잘한 설정

업로드 용량 변경(Changing Upload file size)

북스택을 쓰면 항상 느끼는 것이 "와 아무렇게나 첨부파일을 올릴 수 있다!"도 있습니다.

하지만 용량때문에 업로드가 안될때가 있는데요, 이럴때는 설정을 바꿔줘야 합니다. 
크게 바꿔줘야 하는 설정은 다음과 같습니다. 

NginX 설정 변경

nginx.conf 또는 해당 사이트의 설정( .conf 파일)에서 다음 항목을 넣어줍니다. 특정 사이트만 용량을 올릴 필요가 없을 때는 http {} 블럭에 넣어주셔도 됩니다. 

client_max_body_size 1024M;   # 화끈하게 올려봅니다!
client_body_timeout 2400s;    # 기본값은 60s입니다. 파일용량이 크면 더 올려주시면 됩니다.

넣고 나서는 반드시 다음 명령으로 문법에 오류가 없는지 확인하시고, reload를 해주세요. 

$ sudo nginx -t 
nginx : the configuration file /etc/nginx/nginx.conf systax is ok
nginx : configuration file /etc/nginx/nginx.conf test is successful

$ sudo service nginx reload

nginx -t는 여러분이 만드신 .conf 파일중에 하나만 문제가 있어도 바로 알려줍니다. 그리고 service nginx reload를 하시면 nginx가 재시작되지 않아도 되기 때문에 서비스가 중단되는 일이 없습니다. 

php.ini 설정 변경

일단 find 명령으로 php.ini 파일이 어디에 있는지 찾습니다. 

sudo find / -name "php.ini"     # 루트(/) 디렉터리부터 시작해서 php.ini라는 파일을 모조리 찾아오라는 명령입니다. 
/etc/php/8.3/cli/php.ini
/etc/php/8.3/apache2/php.ini
/etc/php/8.3/fpm/php.ini

위의 예시는 우분투에서 실행한 것이라 FreeBSD에서는 조금 다를 수 있습니다. 
아래에 나온 결과중에 fpm/php.ini 가 우리가 수정해야 하는 파일입니다. 수정해야 하는 곳은 총 다섯군데입니다. 

# nano에서 Ctrl+w 를 눌러서 해당 항목을 입력하면 찾아줍니다.

# 다음은 반드시 On이어야 합니다
file_uploads=On

# 또 화끈하게 올려줍니다!
upload_max_filesize=1024M

# POST 방식으로 올리는 것도 쫙쫙 올려줍니다!
post_max_size=1024M

# 최대 실행시간도 올려줍니다. 60초가 1분이니까 300초면 5분, 1800초면 30분입니다. 
max_execution_time=300

# 메모리를 덜 사용하면 업로드를 못할 수 있으니 올려줍니다. 전 메모리가 남습니다. 우핫핫! 
memory_limit=16384M

여기까지 하셨으면 sudo service --status-all 명령으로 php8.3-fpm 비슷한 이름의 프로세스를 찾아 재시작 해줍니다. 

sudo service --status-all 

sudo service php8.3-fpm restart

BookStack 자체 설정 변경

.env 파일을 수정해주면 됩니다. 다음 내용(#이 없는 것을 넣주시면 됩니다. 단위는 메가바이트입니다)을 추가합니다. 

# File Upload Limit
# Maximum file size, in megabytes, that can be uploaded to the system. 
FILE_UPLOAD_SIZE_LIMIT=1024

php.ini와 다르게 숫자 뒤에 M이 없는 것을 기억하세요. BookStack은 서비스 같은 것을 재시작 하실 필요는 없습니다. 

자잘한 설정

PDF 파일 임베딩하기

다음의 코드를 설정 - 맞춤 - 사용자 지정 HTML 헤드 콘텐츠에 추가합니다. 

<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/2.0.466/pdf.min.js"></script>
<style>
canvas[data-pdfurl] {
  background-color: lightgrey;
   width: 100%;
}
.page-content a {
 color: #39f;
text-decoration: underline;
}
.pdf-wrapper {
position: relative;
height: 80vh;
width: 100%;
}
.pdf-wrapper .download-link {
position: absolute;
top: -2em; 
right: 0;
z-index: 50;
}
.pdf-wrapper .pdf-scroller {
height: 100%;
overflow: auto;
}
</style>
<script type="text/javascript">

  // ------------------- THIS SECTION ADDS A PDF BUTTON TO THE EDITOR TOOLBAR THAT ALLOWS YOU TO EMBED PDFS 

  // Use BookStack editor event to add custom "Insert PDF" button into main toolbar
  window.addEventListener('editor-tinymce::pre-init', event => {
      const mceConfig = event.detail.config;
      mceConfig.toolbar = mceConfig.toolbar.replace('link', 'link insertpdf')
  });

  // Use BookStack editor event to define the custom "Insert PDF" button.
  window.addEventListener('editor-tinymce::setup', event => {
    const editor = event.detail.editor;

    // Add PDF insert button
    editor.ui.registry.addButton('insertpdf', {
      tooltip: 'Insert PDF',
      icon: 'document-properties',
      onAction() {
        editor.windowManager.open({
          title: 'Insert PDF',
          body: {
            type: 'panel',
            items: [
              {type: 'textarea', name: 'pdfurl', label: 'PDF URL'}
            ]
          },
          onSubmit: function(e) {
            // Insert content when the window form is submitted
            editor.insertContent('<p id="bkmrk-%C2%A0%C2%A0">&nbsp;<canvas data-pdfurl="' + e.getData().pdfurl + '"></canvas>&nbsp;</p>');
            e.close();
          },
          buttons: [
            {
              type: 'submit',
              text: 'Insert PDF'
            }
          ]
        });
      }
    });

  });

//-------------------- THE CODE BELOW SHALL BE ACTIVE IN VIEWING MODE TO EMBED PDFS
var renderPdf=function(canvas) {
  var url = canvas.dataset.pdfurl;
  var pdf = null;
  // wrap canvas in div
  var wrapper = document.createElement('div');
  wrapper.className='pdf-wrapper';
  var scroller = document.createElement('div');
  scroller.className='pdf-scroller';
  wrapper.appendChild(scroller);
  canvas.parentNode.insertBefore(wrapper, canvas.nextSibling);
  scroller.insertBefore(canvas, null);

  var downloadLink  = document.createElement('a');
  downloadLink.href = url;
  downloadLink.className="download-link";
  downloadLink.innerText = 'Download PDF now ↓';
  wrapper.appendChild(downloadLink);

  var renderPage = function(page) {
    var scale = 1.5;
    var viewport = page.getViewport(scale);
    // Fetch canvas' 2d context
    var context = canvas.getContext('2d');
    // Set dimensions to Canvas
    canvas.height = viewport.height;
    canvas.width = viewport.width;
    canvas.style.maxWidth='100%';
    // Prepare object needed by render method
    var renderContext = {
      canvasContext: context,
      viewport: viewport
    };
    // Render PDF page
    page.render(renderContext);
    if (currentPage < pdf.numPages) {
      currentPage++;
      var newCanvas = document.createElement('canvas');
      scroller.insertBefore(newCanvas, canvas.nextSibling);
      scroller.insertBefore(document.createElement('hr'), canvas.nextSibling);
      canvas=newCanvas;
      pdf.getPage(currentPage).then(renderPage);
    }
  };
  var currentPage = 1;
  pdfjsLib.getDocument(url)
  .then(function(pdfLocal) {
    pdf = pdfLocal;
    return pdf.getPage(1);
  })
  .then(renderPage);
};


window.addEventListener('DOMContentLoaded', function() {
  Array.prototype.forEach.call(document.querySelectorAll('canvas[data-pdfurl]'), renderPdf);
});
</script>

이후 문서를 작성할 때 다음의 방법을 따릅니다. 

  1. 첨부 파일로 PDF 파일을 첨부합니다. 
  2. 링크를 본문에 붙입니다.
  3. 링크를 링크 복사합니다. 
  4. 위의 링크 삽입/수정 옆의 Insert PDF를 클릭한 후, 나오는 창에 링크를 붙여 넣습니다.
  5. 문서를 저장합니다. 

 

자잘한 설정

웹 사이트에 구글 태그 붙이기

설정 - 맞춤 - 사용자 지정 HTML 헤드 콘텐츠 에 다음을 붙여 넣습니다. 

  <!-- Google tag (gtag.js) -->
  <script async src="https://www.googletagmanager.com/gtag/js?id=TAG_ID"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());

    gtag('config', 'TAG_ID');
  </script>

TAG-ID 부분을 전부 자신의 구글 태그로 변경합니다. 이후 구글 애널리틱스에서 테스트를 하고 추적이 되는지 확인합니다. 

새로 태그를 붙인 후에는 최소 24시간에서 일주일 정도 지나야 실제 통계가 표시됩니다. 

Releases

업데이트된 기능들 간략 정리

Releases

BookStack v24.02

업그레이드 공지

전체 변경 사항 목록