1. 웅덩이 파는 데 포크레인 써보기 2. Design System 흉내를 위해 Figma 힐끗 보기 3. React 기초 훑어보고 Docusaurus 설치하기 4. Docusaurus config 톺아보기 (1) 5. Docusaurus config 톺아보기 (2) 6. Swizzle로 디자인 커스터마이징하기
Docusaurus의 호스팅 방법
Docusaurus 가이드에서는 다양한 호스팅사를 기준으로 호스팅 방법을 설명하고 있다. 대부분이 국내에서 흔히 들어보기 어려운 서비스이고, 그나마 친숙한 서비스가 Github Pages이다. 일반적인 블로그 서비스를 쓰지 않고 직접 개인 홈페이지를 구축할 때 가장 큰 단점 중 하나가 어떻게든 서빙 비용이 든다는 점이다. Github Pages는 내 Github 계정 1개당 1개의 repository를 무료 웹사이트 호스팅 용도로 쓸 수 있게 하는 서비스다. 어차피 버전 관리에 Git을 쓴다면 호스팅 비용도 아낄 겸 Github Pages는 굉장히 편리한 선택이다. Github.io로 도메인이 고정되지만 개인 사이트에서 커스텀 도메인 연결은 필수가 아니라서 큰 단점은 아니고, 꼭 필요하다면 연결하는 것도 가능하다. 물론 나는 서빙 비용도 아끼는 마당에 굳이 도메인 연간 유지비를 쓰고 싶지 않았기 때문에 연결하지 않았다.
Github Pages 사용법
Github Pages 가이드에 간편한 튜토리얼이 설명되어 있어서 첫 세팅 자체는 어렵지 않다. 오히려 어려운 점은 Docusaurus의 Github Pages 호스팅 설정과 Github Pages 설정을 제대로 못한 것인지, Docusaurus의 배포가 제대로 되지 않는 경우가 있었다는 점이다. 아주 예전에 Docusaurus로 처음 개인 홈페이지 개발을 시도했을 때 배포 단계에서 자꾸 문제가 생겨서 포기했었는데, 다행히 이번에는 원활히 배포가 되었다.
Step 1. Github Pages 초기 세팅을 마친다.
- respository 이름이 자신의 Github 계정 Owner 이름 뒤에 .github.io를 붙인 이름이어야 한다.
- respository 공개 여부는 Public이어야 한다.
Github Pages 전용 repository를 만드는 방법은 간단하다. 일반적인 repository를 만드는 경로 그대로 들어가서 위의 2개 조건을 지키기만 하면 된다. 무료로 제공되는 github.io 도메인 앞 부분은 자신이 원하는 문구로 지정할 수 있는 셈이기 때문에 도메인에 살리고 싶은 아이덴티티를 넣고 싶다면 Owner 이름을 바꾸면 된다. Github 자체를 이미 자신의 포트폴리오 용도로 쓰고 있다면 Github Pages 개설용 Github 계정을 하나 새로 만드는 것도 방법일 것이다.
웹상에 공개된 페이지의 호스팅 역할이기 때문에 repository가 public인 셈이라서, 당연히 문제가 될만한 파일은 repository에 올라가지 않게 주의해햐 한다. Docusaurus의 경우 react 기반이라 어차피 전체 소스 코드가 올라가지 않고, build 결과만 올라가기 때문에 이 점은 걱정하지 않아도 된다. 정상적으로 생성됐다면 빈 respository가 만들어져있을 것이다. 이제 Github는 잠깐 내려두고, 다시 Docusaurus로 돌아와야 한다.
Step 2. Docusaurus config 파일에서 호스팅 정보를 설정한다.
앞선 포스팅에서 잠깐 언급한 적 있듯이 config 파일에는 배포 환경 설정 항목이 포함되어 있다.
... (중략) ...
// Set the production url of your site here
url: 'https://winter-blanket.github.io',
// Set the /<baseUrl>/ pathname under which your site is served
// For GitHub pages deployment, it is often '/<projectName>/'
baseUrl: '/',
// GitHub pages deployment config.
// If you aren't using GitHub pages, you don't need these.
organizationName: 'winter-blanket', // Usually your GitHub org/user name.
projectName: 'winter-blanket.github.io', // Usually your repo name.
... (중략) ...
url, organizationName, projectName 이렇게 3개 항목이 Github Pages 배포를 위해 필요한 설정 항목이다. 다양한 호스팅 수단 중 Github Pages가 가장 자주 쓰이는 편인지, Docusaurus 설치 직후에 기본 셋팅되어 있는 config 파일에서 바로 항목을 찾아볼 수 있고 관련 안내 주석도 포함되어 있다. url은 도메인 주소 그 자체를 의미하기 때문에 https://를 포함해서 적어야 하지만, projectName은 repository 이름을 의미해서 https://를 빼고 적으면 된다.
Step 3. deploy 명령어로 Github Pages에 build 파일을 배포한다.
보통 Github repository에 파일을 올리는 과정은 로컬에 git init을 하고, remote 저장소를 연결해준 후, 저장소로 push하는 식이다. Docusaurus에서 제공하는 명령어를 실행하면 config에 설정된 repository로 push 되는데, 로컬에 .git이 만들어져있지 않아도 정 상 push가 되었다. Push할 때 commit 메시지도 알아서 생성된다. 따라서 설정 세팅만 잘 해놓았다면 Docusaurus 명령어 한 번으로 배포를 끝낼 수 있다.
배포하는 명령어는 다음과 같이 구성된다.
GIT_USER={내 Github 계정 Owner 이름} GIT_PASS={내 Github 계정 } CURRENT_BRANCH=main DEPLOYMENT_BRANCH=main yarn deploy
배포 명령어 자체는 yarn deploy 이 부분이고, 앞의 항목은 배포할 때 같이 실어보낼 설정들이다. GIT_USER와 GIT_PASS는 로컬에서 터미널로 Github repository에 접근할 때 소유권을 가진 repository라는 걸 인증하는 역할이다. GIT_USER는 계정 Owner 이름을 적으면 된다. GIT_PASS는 Github 계정 설정에서 만들 수 있는 Personal Access Token을 말한다. CURRENT_BRANCH와 DEPLOYMENT_BRANCH는 배포할 브랜치명을 지정해주는 역할이다. 개인적인 웹사이트 수준에서 굳이 브랜치를 나눠가며 쓸 일은 없어서 main 1개만 쓰고 있다.
GIT_PASS 생성법
Github 프로필 아이콘을 누르면 볼 수 있는 다양한 계정 설정 메뉴 중에서 맨 아래에 Developer Settings라는 메뉴가 있다. 이걸 클릭하면 Personal Access Token이라는 이름의 메뉴를 볼 수 있는데 여기서 Tokens (classic)을 클릭하면 된다. 여기서 Generate new token 버튼을 클릭하면 한 번 더 선택지가 나오는데 Beta가 표시된 버튼이 아니라 classic 쪽을 선택하면 된다. 이렇게 생성한 Token을 GIT_PASS 뒤에 붙여주면 별도의 로그인 절차 없이 터미널에서 바로 repository에 접근할 수 있게 된다.
배포 명령어 실행하기
명령어가 꽤 길기 때문에 적당한 메모장에 저장해뒀다가 복붙으로 터미널에 입력하는 쪽이 편하다. 내 경우는 zsh를 쓰기 때문에 docuDeploy라는 이름으로 alias를 생성해서 간편하게 쓰고 있다. 명령어를 실행하면 꽤 장문의 로그 메시지를 볼 수 있다. 메시지를 살펴보면 배포 명령어 한 번으로 (1) build 생성하기 (2) Git Commit 하기 (3) remote repository에 push하기 이렇게 3개의 과정이 한 번에 진행된다는 점을 알 수 있다.
❯ docuDeploy
yarn run v1.22.19
$ docusaurus deploy
[INFO] Deploy command invoked...
[INFO] organizationName: winter-blanket
[INFO] projectName: winter-blanket.github.io
[INFO] deploymentBranch: main
... (중략) ...
[SUCCESS] Generated static files in "build".
[INFO] Use `npm run serve` command to test your build locally.
... (중략) ...
[INFO] `git rm -rf .` code: 0
[INFO] `git add --all` code: 0
[main 61042b5] Deploy website - based on 8d5c8852cedf30647b1be6cb7905ecbe3d75d88f
71 files changed, 257 insertions(+), 155 deletions(-)
마치며
이제 내 Github Pages 도메인에 접속했을 때 웹페이지가 잘 보인다면 성공이다. 시중 서비스를 쓰지 않고 거의 직접 만들다시피 한 웹사이트를 비용 없이 편리하게 호스팅할 수 있다는 점은 Github Pages의 정말 큰 장점이라고 생각한다. Github Pages 자체에 대해서는 비용 부과가 없지만 Github respository를 사용하므로 Github 유료 기능이 필요할 때 비용이 발생할 것이다. 이제 마지막으로 다음 포스팅에서는 검색 유입이 늘어나도록 구글과 네이버에 사이트를 등록하고 사용자 인사이트를 살펴보는 방법을 기록할 생각이다.
1. 웅덩이 파는 데 포크레인 써보기 2. Design System 흉내를 위해 Figma 힐끗 보기 3. React 기초 훑어보고 Docusaurus 설치하기 4. Docusaurus config 톺아보기 (1) 5. Docusaurus config 톺아보기 (2) 6. Swizzle로 디자인 커스터마이징하기