KXX Tech Blog

Categories

🏃‍♂️‍➡️

Synology NAS에서 Jekyll 블로그 시작하기

🗂️ about-blog
목차

Jekyll을 선택하게 된 이유와 NAS에 설치하는 과정을 안내합니다.
아래 사항을 참고해주세요.

  • 일반적인 Jekyll 운영 방식과는 조금 다릅니다.
  • 가이드는 최신 Synology NAS DSM 를 기준으로 작성되었습니다.

티스토리 vs 개인 서버

블로그를 직접 만들기로 마음먹은 이유

인생 첫 블로그는 네이버 블로그였습니다. 2014년도..쯤이었는데 그게 주류였고 유행이었죠. 그 당시 저는 HTML과 CSS라는 언어를 처음 접했고, 블로그를 통해 마음껏 자랑하고 싶었습니다. 그 시기엔 뭐든 자랑하고 싶으니까… 물론 지금 생각하면..🤦‍♂️

그러나 안타깝게도 네이버 블로그로는 ‘내가 이런 것도 할 줄 안다!’ 하고 자랑하는 게 힘들더라고요.

제가 티스토리를 시작한 이유와 떠난 이유는 같습니다.

좀 더 자유로운 공간

티스토리가 유명 블로그 플랫폼 치고 굉장히 자유로운 것은 맞지만, 그것도 일정 템플릿 안에서 가능한 거라 원하는 기능을 넣으려면 아주 기교를 부려야 합니다. 나름 퍼블리셔인데 수정하고 싶은 게 있어도 과정이 너무 불편하더라고요.

블로그 비교 기존 티스토리 | 현재 개발 중인 블로그

그리고 ABOUT에도 적혀 있지만 개인용 NAS가 생겨서 가벼운 서버 구축이 가능하게 되었습니다. 기술 메모 + 공유용 블로그를 만들고 싶어 하는 저에게 맞춤인 상황이라 구축하게 되었죠.

선택 후 확인할 요소

우선 NAS로 블로그를 만들기로 했으니, 어떻게 만들고 어떻게 운영할지 고민했습니다.기존의 대형 플랫폼 블로그들은 만들어진 공간에 글만 작성하면 배포부터 게시글 등록까지 알아서 해 주었지만, 지금 저에게 있는건 작은 서버 역할을 할 수 있는 NAS 한대와 퍼블리싱 지식 뿐이니까요.

블로그 플로우 비교 블로그 개설부터 글 등록까지의 과정 차이

그리고 최근 마크다운 형식의 가벼운 블로그에 관심을 갖게 되면서, 블로그 생성 도구들을 찾아보게 되었습니다. 이걸 정적 사이트 생성기라고 하더군요.

정적 사이트 생성기?

들어봤는데.. 어디서 들어봤는데...

사실 정적 사이트 생성이 뭔지 잘 몰랐습니다. 사회 초년생인 제가 겪은 실무 프로젝트가 거의 Vue와 React뿐이었을 만큼 제가 일을 시작한 2021년은 두 프레임워크의 시대였거든요. 적어도 제 주변에선 그랬습니다. 그래서 일단 어떤 도구인지부터 찾아보기 시작했습니다.

몇 가지 알아보니 특정 언어를 사용해 HTML 파일로 빌드해서 띄운, 말 그대로 정적 사이트 생성 도구였는데요. 가물가물하지만 예전 프로젝트에서 Gulp(걸프)를 잠깐 사용했었는데 그것과 비슷한 도구였습니다.

이제 어떤 도구를 선택할지 고민해야 합니다. 제가 고민했던 두 가지는 Jekyll과 Gatsby였습니다.

  • Jekyll
  • Gatsby

그리고 Jekyll을 선택했죠.

왜 Gatsby가 아닌가?

Jekyll을 선택한 글의 부제로는 어색하지만 공감하실 분이 많을 것 같습니다. Gatsby도 나름 떠오르는 도구이고 많이 선택하는 추세니까요. 저 역시 Gatsby를 선택하지 않을 이유가 전혀 없었습니다. 직업상 React에 익숙하기도 하고 GraphQL은 경험해 본 적 없지만, API를 아예 모르는 것도 아니었으니까요.

Jekyll과 Gatsby의 비교

항목 Jekyll Gatsby
스택 Ruby + Liquid 템플릿 React + GraphQL
크기 매우 작음 (정적 HTML) 더 큼 (React + JS 번들 포함)
빌드 속도 빠름 (소규모/중간 규모 프로젝트에 적합) 느릴 수 있음 (특히 페이지가 많을 경우)
런타임 리소스 적음 (순수 HTML 렌더링) 많음 (Hydration으로 외엔 JS 실행 필요)
목적 블로그, 단순 웹사이트 대규모 사이트, 동적 웹 애플리케이션

Ruby와 Liquid는 접해 본 적 없던 것에 비해 Gatsby의 자바스크립트 활용도가 높다는 점은 확실히 큰 메리트였죠.

그럼에도 제가 Jekyll을 선택한 이유는 지극히 개인적입니다. 만약 누군가 둘 중 고민한다면 저와 같은 상황이 아니라는 전제하에 저는 Gatsby를 추천하고 싶네요.

아무튼.. 아래 세 가지 이유로 저는 Jekyll을 선택하게 됐습니다. 🫠

NAS의 성능

우선 저는 NAS의 Container Manager (구 Docker)로 돌리는 컨테이너가 6개 정도입니다. 그중 24시간 돌아가는 API 서버도 포함되어 있죠. 유의미한 이용자는 없지만.. 🥲 제가 하는 사이드 프로젝트가 추가될수록 컨테이너가 늘어갈겁니다.

NAS 리소스 모니터 기존 램은 2GB, + 16GB 증설한 상태

물론 램을 증설하기도 했고, 블로그의 점유율이 그렇게 높을 거라 생각하진 않지만 이 NAS는 앞으로 해야 할 일이 많기 때문에..부하를 최대한 줄이고 싶었습니다. 그래서 Jekyll이 가볍게 돌리기엔 훨씬 적합하다 생각했죠.

개발 속도

React를 못 하는 건 아니지만 블로그 개발 자체는 Jekyll이 빠를 것 같다는 생각이 지배적이었습니다. 물론 이때는 설치 과정에서 몇몇 문제 있을거란걸 생각 못했죠. 제가 기획한 블로그는 동적인 인터랙션은 거의 없고, 디자인도 단순해서 인터넷 메모장이라고 생각될 정도의 블로그였거든요.

그리고 지금까지 Jekyll의 지원 기간 덕분에 사용자가 만든 테마가 많아서 빠르게 만들고 이후에 수정하는 게 가능했죠. (이 부분은 Gatsby도 비슷합니다.)

블로그 개설의 목적

이것도 한몫했는데요.
이 블로그는 저의 정보를 공유하여 도움을 주는 게 목적입니다. NAS에 Jekyll을 올리시는 분은 많지만 Gatsby를 올리시는 분은 없더라고요. 지금은 구축을 완료했지만 Jekyll을 선택하신 분들에게, 그중에서도 NAS에 설치하시는 분들에게 도움이 되는 글을 쓰고 싶었습니다. 👻

NAS + Jekyll. 어떤점이 다른가?

아래 설치 과정에서 추가 설명하겠지만, 먼저 개념 차이를 알고가는게 좋습니다.

운영 환경

일반적으로 Jekyll은 보통 로컬 머신에서 Jekyll을 실행한 후, 결과물인 _site 폴더를 호스팅 서버(예: GitHub Pages, Netlify)에 업로드합니다.

NAS에 설치해 운영하는 Jekyll 은 NAS 자체가 웹 서버 역할을 하므로, Jekyll의 결과물(_site)을 NAS 내의 웹 디렉터리(Web Station, Apache/Nginx 등)로 직접 배치하거나, Jekyll 자체를 NAS의 컨테이너에서 실행할 수 있습니다.

빌드 및 배포

일반적으로 Jekyll은 로컬 개발 환경에서 Jekyll build를 실행하거나, GitHub Actions 같은 CI/CD 파이프라인을 통해 자동 빌드 및 배포를 설정합니다.

NAS에 설치해 운영하는 Jekyll 은 NAS에서 Jekyll 빌드를 실행하려면 Ruby와 Jekyll이 설치되어 있어야 하기때문에 Container Manager를 이용해 컨테이너 안에서 Jekyll을 빌드하고 _site 폴더를 NAS의 웹 스테이션으로 마운트하거나, 로컬 서버로 띄운 뒤 포트포워딩으로 외부에 노출하는 방식을 선택합니다.

이 글에서는 Jekyll 로컬 서버를 직접 띄우는 과정을 다룰건데, 두 방식이 크게 다르지 않기 때문에 어느정도 개념을 알게된다면 쉽게 바꿀 수 있을겁니다.

아래부터는 Jekyll 설치 가이드입니다.

도커는 무적이다. SSH는 신이고.

NAS에서 Jekyll을 설치하는 과정

우선 과정은 이렇습니다.

  1. 적당한 Jekyll 테마 찾기
  2. Jekyll 컨테이너 매핑과 권한 설정
  3. 임시 컨테이너로 bundle install
  4. Jekyll 블로그 컨테이너 생성
  5. 실행 명령과 빌드 방식에 관해
  6. 실행 명령 선택하기
  7. Web Station 설정

적당한 Jekyll 테마 찾기

Container Manager에서 바로 Jekyll 이미지를 다운받아 컨테이너로 실행하면 오류만 나고 아무것도 할 수 없습니다. 기본적인 블로그 템플릿을 받아줘야되는데요. Jekyll에선 테마라고 부릅니다. 사용자가 커스텀한 Jekyll 블로그의 파일들인데,
여기에 Node.js의 Package.json의 역할을 하는 Gemfile이 포함 되어있습니다.

Gem은 Jekyll의 기반 언어인 Ruby의 패키지를 뜻하는데, 이렇게 생각해도 좋습니다.

  • Gem = 기능
  • Gemfile = 설치 할 기능 목록

쉽게 말하면 내 블로그에서 사용 될 기능을 정리한 파일입니다.
이후 설치 과정에서 Gemfile에 정의된 기능들이 설치되어야 빌드된 사이트에서 해당 기능이 사용 가능해지는거죠.

테마는 아래 사이트에서 찾을 수 있습니다.

마음에 드는 테마를 찾고 다운받아주세요.

Jekyll 컨테이너 매핑과 권한 설정

다운받은 테마를 열어보면 여러 폴더들과 Gemfile이란게 있을겁니다.
테마 안의 내용물을 모두 블로그로 빌드시킬 폴더에 옮겨주세요.

젬파일 확인 Gemfile 확인

저같은 경우 /docker/blog-test폴더를 만들어 옮겼습니다.

이제 ssh를 통해 Jekyll 컨테이너와 /docker/blog-test폴더의 매핑을 진행할겁니다.
우선 /docker/blog-test위치에 /vendor/bundle 폴더를 하나 만들어야하는데요. Gem들이 설치되는 폴더인데 테마에는 기본적으로 포함되지 않습니다.

아래 명령어 또는 NAS File Station으로 직접 진행하시면 됩니다.

sudo mkdir -p /volume1/docker/blog-test/vendor/bundle

폴더 생성이 끝났으면 Jekyll 컨테이너가 파일을 읽기/쓰기 할 수 있도록 권한을 설정해줍니다.

권한 설정 팝업 생성한 폴더 docker/blog-test 폴더 우클릭 > 속성

Everyone 그룹에 읽기, 쓰기 권한을 주면 끝입니다.

임시 컨테이너로 bundle install

폴더 생성이 확인 됐다면 이제 Jekyll 이미지로 컨테이너를 임시로 만들어 bundle install을 진행할겁니다.

지금 단계에서 ssh를 통해 만드는 컨테이너는 install을 위해서 만드는 컨테이너라 --rm 명령어를 통해 작업 완료 후 자동으로 제거되게합니다.

이때 제가 진행한 Jekyll 버전은 3.8.6인데요. 다른 버전은 폴더 구조가 달라질 수 있다는 얘기가 있어서, 저도 이부분은 참고한 자료를 따라가는점 양해부탁드립니다.

아래 명령어로 install을 진행합니다.

docker run --rm --network host
     -v "/volume1/docker/blog-test:/srv/jekyll"
     -v "/volume1/docker/blog-test/vendor/bundle:/usr/local/bundle"
     -it jekyll/jekyll:3.8.6 bundle install

-v 옵션으로 폴더를 매핑합니다. 형식은 [NAS 폴더]:[Container 폴더]로, NAS의 실제 경로와 컨테이너 내부의 경로를 연결합니다.

이후 jekyll 이미지를 다운받아 bundle install을 진행합니다. 이 과정은 Gemfile에 정의된 모든 의존성 패키지를 설치하는 작업입니다.

젬파일 확인 bundle install 과정

설치가 다 되었다면 컨테이너는 자동으로 삭제될겁니다.
어느정도 기다렸는데 멈춰있다 싶으면 Ctrl + C로 직접 종료시켜주세요.

젬파일 확인 임시로 생성되는 컨테이너. 작업 완료 후 자동 삭제됩니다.

설치가 정상적으로 됐다면 이전에 생성한 /vendor/bundle 폴더에 여러 파일들이 생성되어있을겁니다.

젬파일 확인 bundle install 후 생성된 폴더들

이제 필요한 의존성 파일들이 모두 설치되었으니, Container Manager를 통해 Jekyll 서비스용 컨테이너를 생성하겠습니다.

Jekyll 블로그 컨테이너 생성

젬파일 확인 컨테이너 매니저 (도커)로 Jekyll 컨테이너 생성

bundle install 할 때 이미지를 받았으니 아마 jekyll/jekyll:3.8.6이미지가 이미 있을겁니다.
Web Station의 경우 원래는 4000 포트인데, 저는 테스트 용으로 또 만드는거라 35729 포트인 점 참고해주세요.

만약 4000 외의 포트를 사용하려면 이후에 _config.yml 파일에 port를 추가해야합니다.

port: 35729

다음은 폴더 마운트인데, ssh로 install할 때의 마운트와 동일합니다.
명령어를 확인해보시면 쉽게 가능합니다.

젬파일 확인 폴더 마운트. ssh에서 진행한 마운트 경로와 동일

여기는 개인에 맞게 수정하면 되는데요.

환경변수는 아무것도 수정하지 않아도 상관은 없습니다.
저는 LANG, LANGUAGE, TZ 을 대한민국에 맞게 수정했었는데 실제 빌드 후 어떤게 달라지는지는 모르겠습니다.. 😅

실행 명령과 빌드 방식에 관해

다음은 실행 명령인데요.

젬파일 확인 정말 힘들었네요.

이 부분은 많은 시행착오와 검색 끝에 jekyll serve또는 jekyll build -w가 중론임을 알았습니다. 시행착오 과정이 궁금하시다면 글을 계속 읽어주세요. 바로 진행을 원하시는 분은 아래 사진처럼 하시거나 실행 명령 선택하기으로 가시면 됩니다.

실행 명령 serve 명령어는 수정사항을 라이브로 반영합니다.

다른 명령어를 사용해도 컨테이너만 다시 만들면 바꿀 수 있어서 상관없지만,
Container Manager의 실행 명령은 하나만 실행한다는 점 유의해주세요.

명령어를 입력하기 전에 보통의 정적 사이트 생성 블로그 배포 방식과 NAS 환경의 차이를 다시 살펴보죠. 위에서 간단하게 설명했지만 정적 사이트 생성 방식은 템플릿과 콘텐츠를 결합해 미리 렌더링된 HTML 파일을 생성합니다. 이 HTML 파일은 웹 서버에서 그대로 제공되며, 브라우저가 로드 시 스타일(CSS)과 동적 기능(JavaScript)을 추가적으로 불러와 완전한 웹 페이지를 렌더링하는 방식인데요.

이때 렌더링할 파일을 생성하는 과정을 빌드(build) 라고 합니다. Jekyll은 주로 GitHub Pages를 통해 배포되는데, GitHub Pages와 이 글에서 다루는 NAS 배포 방식은 차이가 조금 있습니다.

우선 github pages를 통해 Jekyll 배포하는 과정은 다음과 같습니다.

github pages를 통한 배포 로컬과 서버 공간이 나뉘어져있다.

사진처럼 GitHub Pages의 경우, 로컬에서 작업한 내용은 git push 명령을 통해 원격 저장소로 푸시하지 않는 한 로컬에만 남습니다. 푸시 이후에는 GitHub의 CI/CD 파이프라인이 자동으로 빌드 및 배포를 처리합니다. 이를 통해 로컬 PC에서는 serve 또는 serve --drafts 명령어를 사용해 로컬 서버에서 작업 중인 페이지를 실시간으로 확인할 수 있으며, 이 과정은 배포된 사이트에 영향을 주지 않습니다. 로컬과 서버의 코드를 따로 유지할 수 있는 git의 장점이죠

그러나 NAS 에서는 조금 다릅니다. 애초에 Jekyll을 NAS에 설치하고 블로그 작업도 NAS하는게 대부분이죠.

Jekyll을 배포하는 NAS의 _posts 폴더를 통해 바로 글을 작성하기 때문에 사용자의 수정사항이 실시간으로 반영됩니다. 그리고 serve 명령어에는 build 과정이 포함되어있기 때문에 블로그 폴더 자체를 두개로 분리 (빌드용, 테스트용)하지 않는 이상 수정사항이 실시간으로 반영되는걸 막을 수는 없었습니다.

“그럼 글을 미리 보는 방법은 없는건가요?”

아예 방법이 없는건 아닙니다.
위의 예 처럼 로컬 PC에 Jekyll을 설치해 작업하다가 빌드된 파일만 NAS에 올리는 방법도 있고, vs code의 extension을 이용해 .md파일의 결과를 미리 보는 방법도 있습니다. 저는 vs code + drive client 동기화로 글을 관리하는데, 이부분은 블로그 생성 이후의 이야기라 다른 글로 다시 다루겠습니다.

NAS에서 배포 Jekyll을 설치한 NAS서버에서 파일을 바로 수정한다.

실행 명령 선택하기

  • jekyll serve: 수정사항 실시간 반영. 소규모 블로그나 빠른 테스트에 적합.
  • jekyll build -w: 빌드된 정적 파일 생성. 대규모 배포나 CI/CD와 결합 가능.

현재 상황에 맞게 선택하면 됩니다.
저는 현재 개발 초기 단계이므로 serve로 로컬을 그대로 띄우는 방식으로 운영중입니다. 이 방식은 수정사항을 즉시 확인할 수 있어 초기 구축 단계에서 유용합니다. 이후 git CI/CD 작업을 하기전까진 serve로 유지할 계획입니다.

이제 바로 Web Station 설정으로 가시면 됩니다.

Web Station 설정

아마 완료 후 Web Station으로 이동하게 될텐데요.

원하는 방식으로 생성 웹 스테이션에서 사이트 배포

원하는 방식으로 포털을 설정한 후 생성하면 끝입니다.

저는 제 블로그 이름 기반으로 한 뒤,
따로 포트포워딩 한 포트로 설정해줬습니다.

완성

해당 주소로 접속하여 확인해봅시다.

정상 작동하는 블로그 제대로 나온다!

이제 ‘개인용’ 블로그는 완성되었습니다..만, 공간만 마련됐을 뿐 입니다. 실제로 블로그 역할을 하기 위해서는 할 일이 아직 많습니다. 구글 서치 콘솔 등록이나 사이트맵, robots.txt 같은 작업들이 필요하죠. 해당 내용까지 한번에 담기엔 글이 너무 길어지는 감이 있어서 다른 글로 또 작성해보겠습니다.

긴 글 읽어주셔서 감사합니다. 🙇‍♂️