마크다운 기반의 블로그(정적 사이트 생성기)는 많지만 마크다운 기반의 위키는 생각보다 많지 않은데, Gollum을 이용하면 git & 마크다운 기반의 위키를 손쉽게 구축할 수 있다.

이 포스트에서는 골룸과 Docker를 이용해서 위키 애플리케이션을 구축하는 방법을 정리해 보았다. 구축한 애플리케이션을 호스팅하는 방법은 다음 포스트에 정리했다.

골룸은 루비 기반의 위키 엔진이므로 설치하고 가동하려면 루비가 필요하다. 그러나 이 포스트에서는 도커를 사용할 예정이므로 머신에 직접 루비 환경을 설치할 필요는 없다.

만약 Disqus 연동이 필요하다면, 골룸의 템플릿을 커스텀해야 하므로(골룸 코드의 복사-붙여넣기가 필요하다), 루비와 골룸을 모두 시스템에 설치하는 것이 좋다. 루비 설치는 이 곳을 참고하면 된다.

Docker 이미지 제작

그럼 바로 도커 이미지를 작성해보자. 기본적으로는 골룸의 도커 가이드를 참고했다.

FROM ruby

RUN apt-get -y update && apt-get -y install libicu-dev cmake && rm -rf /var/lib/apt/lists/*
RUN gem install github-linguist
RUN gem install gollum
RUN gem install unicorn

WORKDIR /wiki
RUN mkdir tmp

CMD ["unicorn", "-d", "-c", "unicorn.rb"]
EXPOSE 80

가이드와 거의 유사하지만, Unicorn을 사용했다는 차이가 있다. 골룸을 설치하고 gollum 명령어로 실행하면 Webrick이라는 개발용 Rack 서버를 띄우는데, Webrick은 프로덕션 환경에 부적합하기 때문에 Unicorn으로 교체해주었다.

Unicorn 설정 파일

Unicorn의 가동 옵션을 unicorn.rb라는 파일에 작성하고 Unicorn을 실행할 때 적용해준다. 워커의 개수, 타임아웃 시간, 포트, pid와 로그 파일의 위치 등을 지정해준다.

@dir = File.join(File.dirname(__FILE__), "")
@tmp = File.join(@dir,"tmp")
Dir.exists?(@tmp) || Dir.mkdir(@tmp)

worker_processes 2
working_directory @dir

timeout 30

listen "0.0.0.0:80", :backlog => 64
pid File.join(@tmp, "unicorn.pid")
stderr_path File.join(@tmp, "unicorn.stderr.log")
stdout_path File.join(@tmp, "unicorn.stdout.log")

Rack 애플리케이션으로서의 Gollum

공식 가이드에 의하면 위키 저장소 안에 config.ru 파일을 통해 골룸 위키를 Rack 애플리케이션으로 만들 수 있다. 동시에 각종 실행 옵션 등으로 커스텀도 가능하다. 특히 여기서는 template_dir 옵션을 /wiki/templates로 주었다는 것에 유념하자.

require 'rubygems'
require 'gollum/app'

gollum_path = File.expand_path(File.dirname(__FILE__))

wiki_options = {}
wiki_options[:universal_toc] = false
wiki_options[:allow_editing] = false
wiki_options[:live_preview] = false
wiki_options[:allow_uploads] = false
wiki_options[:show_all] = false
wiki_options[:h1_title] = true
wiki_options[:template_dir] = '/wiki/templates'

Precious::App.set(:gollum_path, gollum_path)
Precious::App.set(:default_markup, :markdown)
Precious::App.set(:wiki_options, wiki_options)

run Precious::App

골룸의 다양한 실행 옵션은 이 곳을 참조하면 된다.

Disqus 설치

골룸에는 기본적으로 댓글 시스템이 없으므로, Disqus 등으로 댓글을 붙이려면 커스텀이 필요하다. 이 페이지를 참고했다.

템플릿 복사

  1. 골룸 라이브러리 내부의 템플릿 코드를 수정해야 하므로, 라이브러리의 템플릿을 통째로 카피해서 저장소의 디렉토리로 옮겨야 한다.
  2. 골룸의 기본 템플릿은 gem으로 설치한 라이브러리들의 위치를 찾아보면 된다.
  3. 저장소에 templates 디렉토리를 만들고 골룸의 기본 템플릿을 모두 이곳으로 카피한다.

만약 맥에서 rbenv으로 루비와 골룸을 설치했을 경우, 경로는 /Users/<username>/.rbenv/versions/<rubyversion>/lib/ruby/gems/<rubyversion>/gems/gollum-<gollumversion>/lib/gollum/templates이 될 것이다. (머신이나 버전마다 다를 수 있음)

그리고 바로 위에서 했던 template_dir 옵션을 방금 만든 디렉토리(Docker 내부 경로이므로 /wiki/templates)로 바인딩 하면 카피한 템플릿을 이용할 수 있다.

Disqus 추가

커스텀 템플릿 디렉토리에 comments.mustache 파일을 추가하고 Disqus Universal Code를 붙여 넣는다. Disqus Universal Code는 Disqus의 Admin에서 얻을 수 있다.

install-disqus

이제 모든 위키 페이지가 comments.mustache 템플릿 조각을 포함하도록 page.mustache 파일의 markdown-body 클래스를 가진 div 태그 아래에 다음 코드를 추가한다.

<div class="markdown-body">
    {{{content}}}
</div>

{{>comments}}  <!-- 추가한 코드 -->

변경사항을 커밋하고 다시 접속해보면 모든 페이지에서 Disqus가 활성화된 것을 볼 수 있다.

Docker 이미지 실행

docker-compose.yml 파일을 작성해서 간단하게 실행해보자.

version: '3.0'

services:
  wiki:
    image: gollum
    container_name: gollum
    ports:
      - '80:80'
    volumes:
      - '/root/wiki:/wiki'

호스팅을 하려면 80 포트로 서빙을 하는 것이 좋으므로 이에 맞춰서 포트를 연결해준다. 그리고 다음과 같이 실행한다.

docker-compose up -d

브라우저에서 접속해보면 위키 애플리케이션을 확인할 수 있다. 이제 마크다운 형식을 이용해 문서를 작성해보자!

호스팅과 SSL 적용

다음 포스트에서,

  1. 고대디 GoDaddy로 도메인을 사고,
  2. 디지털오션 DigitalOcean을 이용해서 호스팅을 하고,
  3. 클라우드플레어 Cloudflare로 SSL을 적용해 본다.