메인 컨텐츠로 이동
Version: 2.0.0-alpha.75

배포

웹 사이트에 게시할 파일을 빌드하기 위해서 아래 명령을 실행합니다.

npm run build

명령을 실행하면 build/ 디렉터리 아래에 파일이 생성됩니다.

여러분의 사이트는 베르셀(Vercel), 깃허브 페이지(GitHub Pages), 네트리파이(Netlify), 렌더(Render), 서지(Surge) 같은 파일 호스팅 서비스로 배포할 수도 있습니다. 도큐사우루스 사이트는 정적인 파일로 만들어지며 자바스크립트 없이 동작할 수 있습니다.

로컬에서 빌드 테스트하기#

실제 배포 작업을 진행하기 전에 빌드 테스트를 진행해야 합니다. 도큐사우루스는 로컬 빌드 테스트를 위한 docusaurus serve 명령을 지원합니다.

npm run serve

웹 서버를 구축하고 직접 호스팅하기#

warning

권장하는 방법은 아닙니다.

도큐사우루스에서 docusaurus serve 명령을 사용해 직접 호스팅할 준비를 할 수 있습니다. --port 옵션에서 포트를 변경하고 --host 옵션에서 호스트를 변경합니다.

npm run serve -- --build --port 80 --host 0.0.0.0

깃허브 페이지(GitHub Pages)를 사용해 배포하기#

도큐사우루스에서는 깃허브 페이지를 사용한 배포를 간단하게 할 수 있도록 지원합니다. 깃허브 페이지는 모든 깃허브 저장소에서 무료로 사용할 수 있는 호스팅 서비스입니다.

docusaurus.config.js 파일 설정하기#

먼저 docusaurus.config.js 파일에서 필요한 몇 가지 항목을 추가해주어야 합니다.

옵션명설명
organizationName코드 저장소를 소유하고 있는 깃허브 사용자 또는 그룹 계정을 설정합니다. 여러분이 저장소 소유자라면 깃허브 username으로 설정합니다. 도큐사우루스 같은 경우 그룹 계정인 "facebook"이 깃허브 저장소의 소유자입니다.
projectName깃허브 저장소 이름을 설정합니다. 예를 들어 도큐사우루스 저장소 이름은 "docusaurus"이고 프로젝트명도 "docusaurus"로 설정합니다.
url깃허브 페이지의 URL을 설정합니다. 일반적인 경우 https://_username_.github.io 형식으로 URL을 사용합니다.
baseUrl여러분의 프로젝트를 위한 Base URL을 설정합니다. 깃허브 페이지에서 호스팅하게 되는 프로젝트를 가리킵니다. "/projectName/" 형식을 사용합니다. https://github.com/facebook/docusaurus이라면 baseUrl/docusaurus/이 됩니다.
info

깃허브 페이지에 여러분이 가지고 있는 도메인을 연결하기 원한다면 static 디렉터리 안에 CNAME 파일을 만들어줍니다. static 디렉터리 아래 있는 파일은 모두 배포 시 build 디렉터리 아래로 복사됩니다.

좀 더 자세한 내용은 깃허브 페이지 가이드 문서를 참고하세요.

예:

docusaurus.config.js
module.exports = {  // ...  url: 'https://endiliey.github.io', // 여러분의 웹 사이트 URL  baseUrl: '/',  projectName: 'endiliey.github.io',  organizationName: 'endiliey',  // ...};
warning

기본적으로 깃허브 페이지는 지킬을 통해 게시된 파일을 실행합니다. 지킬은 _로 시작하는 모든 파일을 삭제합니다. 때문에 static 디렉터리에 .nojekyll라는 이름을 가진 빈 파일을 추가해 지킬을 비활성화하는 것을 권장합니다.

환경 설정#

환경 변수로 깃 사용자를 설정합니다.

옵션명설명
GIT_USER저장소에 커밋 권한을 가지고 있는 깃허브 계정 사용자명입니다. 여러분이 소유자인 저장소라면 사용하고 있는 깃허브 사용자명을 설정합니다. GIT_USER에 설정한 계정은 organizationNameprojectName 조합으로 지정한 저장소에 업로드(push) 권한을 가지고 있어야 합니다.

환경 변수에서 추가로 설정할 수 있는 옵션은 아래와 같습니다.

옵션명설명
USE_SSH깃허브 저장소에 연결 시 기본 HTTPS 대신 SSH를 사용하려면 true로 설정합니다.
DEPLOYMENT_BRANCH웹 사이트가 배포되는 브랜치는 일반 저장소인 경우에는 gh-pages가 기본값이며 저장소 이름이 github.io으로 끝나는 경우에는 master가 기본값입니다.
CURRENT_BRANCH배포할 최신 문서를 포함하고 있는 브랜치를 설정합니다. 일반적인 경우는 master 브랜치가 되겠지만, gh-pages를 제외한 어떤 브랜치(기본값 또는 다른)를 사용해도 괜찮습니다. 값을 설정하지 않으면 현재 브랜치를 사용합니다.
GIT_PASS 사용자(GIT_USER으로 설정한)의 비밀번호(또는 토큰)을 설정합니다. 값을 설정하면 사용자 개입 없이 지속적인 배포(continuous deployment) 작업을 처리할 수 있습니다.

깃허브 엔터프라이즈를 사용하는 경우에도 깃허브와 다르지 않습니다. 환경 변수에 깃허브 엔터프라이즈에서 사용하는 그룹 계정을 설정해주기만 하면 됩니다.

옵션명설명
GITHUB_HOST깃허브 엔터프라이즈 사이트에서 사용하는 도메인 이름을 설정합니다.
GITHUB_PORT깃허브 엔터프라이즈 사이트에서 사용하는 포트를 설정합니다.

배포#

이제 아래 명령을 사용해 여러분의 사이트를 깃허브 페이지로 배포합니다.

GIT_USER=<GITHUB_USERNAME> yarn deploy

깃허브 액션(GitHub Actions)을 사용해 자동으로 배포하기#

깃허브 액션은 여러분의 저장소에서 소프트웨어 배포를 자동으로 원하는 형태로 실행할 수 있도록 지원합니다. 여러분의 문서는 저장소의 documentation 브랜치에 있고 배포할 파일gh-pages 브랜치에 설정되어 있다고 가정해보죠.

  1. 새로운 SSH 키를 만듭니다.
  2. 기본적으로 여러분의 공개키는 ~/.ssh/id_rsa.pub에 만들어지거나 이전 단계에서 깃허브 배포 키로 추가한 키 이름을 사용할 수 있습니다.
  3. xclip -sel clip < ~/.ssh/id_rsa.pub 명령으로 키를 클립보드에 복사하고 저장소에 배포키로 붙여넣습니다. 명령행 도구를 사용하기 곤란하다면 파일 콘텐츠를 복사할 수 있습니다. 배포키를 저장하기 전에 Allow write access 박스에 체크해주어야 합니다.
  4. 도큐사우루스에서 배포를 자동으로 처리할 수 있도록 허용하려면 깃허브 보안 설정에서 개인키를 설정해주어야 합니다.
  5. xclip -sel clip < ~/.ssh/id_rsa 명령을 사용해 개인키를 복사하고 깃허브 보안 설정에서 GH_PAGES_DEPLOY 항목에 붙여넣습니다. 명령행 도구를 사용하기 곤란하다면 파일 콘텐츠를 복사할 수 있습니다. 보안 설정을 저장합니다.
  6. .github/workflows/ 경로에 문서를 위한 워크플로우 파일을 만듭니다. 아래 documentation.yml 파일 예시를 참고하세요.
    warning

    아래 예에서 actions@github.com 이메일은 여러분의 깃헙 계정으로 gh-actions 항목은 여러분의 이름으로 변경해주어야 합니다.

documentation.yml
name: documentation
on:  pull_request:    branches: [documentation]  push:    branches: [documentation]
jobs:  checks:    if: github.event_name != 'push'    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v1      - uses: actions/setup-node@v1        with:          node-version: '12.x'      - name: Test Build        run: |          if [ -e yarn.lock ]; then          yarn install --frozen-lockfile          elif [ -e package-lock.json ]; then          npm ci          else          npm i          fi          npm run build  gh-release:    if: github.event_name != 'pull_request'    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v1      - uses: actions/setup-node@v1        with:          node-version: '12.x'      - uses: webfactory/ssh-agent@v0.5.0        with:          ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}      - name: Release to GitHub Pages        env:          USE_SSH: true          GIT_USER: git        run: |          git config --global user.email "actions@github.com"          git config --global user.name "gh-actions"          if [ -e yarn.lock ]; then          yarn install --frozen-lockfile          elif [ -e package-lock.json ]; then          npm ci          else          npm i          fi          npm run deploy
  1. 이제 새로운 풀 리퀘스트가 저장소의 documentation 브랜치에 도착하면 빌드가 제대로 처리됐는지 자동으로 확인합니다.
  2. 풀 리퀘스트가 documentation 브랜치에 병합되거나 누군가 documentation 브랜치에 직접 파일을 밀어넣은 경우 빌드가 진행되며 gh-pages 브랜치로 배포됩니다.
  3. 이런 단계를 거쳐 여러분의 문서는 깃허브 페이지에서 최신 상태를 유지하게 됩니다.

트래비스 CI(Travis CI)를 사용해 자동으로 배포하기#

지속적인 통합(CI) 서비스는 저장소에 새로운 커밋이 발생할때마다 반복적으로 발생하는 작업을 처리하기 위해 사용합니다. 지속적인 통합 환경에서는 단위 테스트, 통합 테스트, 자동 빌드, NPM 배포, 변경된 내용을 웹 사이트에 배포하기 같은 복합적인 작업을 처리할 수 있습니다. 자동으로 웹 사이트 업데이트를 처리하기 위해서는 웹 사이트가 변경됐을때 yarn deploy 스크립트를 호출하기만 하면 됩니다. 지속적인 통합 환경으로 많이 사용하고 있는 트래비스 CI에서 어떻게 도큐사우르스를 배포할 수 있는지 살펴보겠습니다.

  1. https://github.com/settings/tokens에 접속해서 새로운 개인용 접근 토큰을 만듭니다. 토큰을 만들 때 필요한 권한을 가질 수 있도록 repo 범위를 체크해주어야 합니다.
  2. 깃허브 사용자 계정을 사용해 활성화하고자 하는 저장소에 트래비스 CI 앱을 추가합니다.
  3. 트래비스 CI 대시보드를 실행합니다. 대시보드 URL은 https://travis-ci.com/USERNAME/REPO 형식입니다. 대시보드에서 More options > Setting > Environment Variables 항목을 선택합니다.
  4. 새로 만든 토큰을 사용해 GH_TOKEN라는 이름으로 환경 변수를 만들고 GH_EMAIL(이메일 주소), GH_NAME(깃허브 사용자 이름) 환경 변수도 만들어줍니다.
  5. 아래와 같은 내용으로 저장소 루트에 .travis.yml 파일을 만들어줍니다.
.travis.yml
language: node_jsnode_js:  - '10'branches:  only:    - mastercache:  yarn: truescript:  - git config --global user.name "${GH_NAME}"  - git config --global user.email "${GH_EMAIL}"  - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc  - yarn && GIT_USER="${GH_NAME}" yarn deploy

이제 master 브랜치에 새로운 커밋이 발생하면 트래비스 CI는 테스트 스위트를 실행하고 모든 테스트가 통과되면 yarn deploy 스크립트가 실행되어 여러분의 웹사이트를 배포하게 됩니다.

애저 파이프라인(Azure Pipeline) 사용하기#

  1. 계정이 없다면 먼저 애저 파이프라인에서 계정을 만듭니다.
  2. 그룹 계정(organization)을 만들고 그룹 계정으로 프로젝트를 만듭니다. 그리고 깃허브 저장소를 연결합니다.
  3. https://github.com/settings/tokens에 접속해서 새로운 개인용 접근 토큰을 만들고 repo 범위를 체크해줍니다.
  4. 프로젝트 페이지(https://dev.azure.com/ORG_NAME/REPO_NAME/_build 형식입니다)에서 다음 내용을 참고해서 새로운 파이프라인을 만듭니다. 'edit' 버튼을 클릭해서 새로 만든 토큰을 사용해 GH_TOKEN라는 이름으로 환경 변수를 만들고 GH_EMAIL(이메일 주소), GH_NAME(깃허브 사용자 이름) 환경 변수도 만들어줍니다. 환경 변수는 secret로 설정되어야 합니다. 다른 방법으로는 아래와 같은 내용으로 azure-pipelines.yml 파일을 저장소 루트에 만들어줍니다.
azure-pipelines.yml
trigger:  - master
pool:  vmImage: 'ubuntu-latest'
steps:  - checkout: self    persistCredentials: true
  - task: NodeTool@0    inputs:      versionSpec: '10.x'    displayName: 'Install Node.js'
  - script: |      git config --global user.name "${GH_NAME}"      git config --global user.email "${GH_EMAIL}"      git checkout -b master      echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc      yarn && GIT_USER="${GH_NAME}" yarn deploy    env:      GH_NAME: $(GH_NAME)      GH_EMAIL: $(GH_EMAIL)      GH_TOKEN: $(GH_TOKEN)    displayName: 'yarn install and build'

드론 CI(Drone CI) 사용하기#

  1. 프로젝트에서 배포키로 사용할 SSH 키를 새로 만듭니다.
  2. 다른 SSH 키를 덮어쓰지 않도록 주의해서 개인키와 공개키 이름을 설정합니다.
  3. https://github.com/USERNAME/REPO/settings/keys에 접속해서 배포키를 앞에서 만든 공개키 값으로 설정합니다.
  4. 드론 CI 대시보드에 로그인합니다. 연결할 URL은 https://cloud.drone.io/USERNAME/REPO 형식입니다.
  5. 저장소를 선택하고 'activate repository' 버튼을 클릭합니다. 그리고 이름은 git_deploy_private_key, 값은 앞에서 만든 개인키로 지정한 secret를 추가합니다.
  6. 아래와 같은 내용으로 저장소 루트에 .drone.yml 파일을 만들어줍니다.
# .drone.ymlkind: pipelinetype: dockertrigger:  event:    - tag- name: Website  image: node  commands:    - mkdir -p $HOME/.ssh    - ssh-keyscan -t rsa github.com >> $HOME/.ssh/known_hosts    - echo "$GITHUB_PRIVATE_KEY > $HOME/.ssh/id_rsa"    - chmod 0600 $HOME/.ssh/id_rsa    - cd website    - npm i    - npm run publish-gh-pages  environment:    USE_SSH: true    GIT_USER: $DRONE_COMMIT_AUTHOR    GITHUB_PRIVATE_KEY: git_deploy_private_key

이제 깃허브에 새로운 태그가 들어오면 여러분의 웹 사이트를 배포하기 위한 드론 CI 동작이 자동으로 시작됩니다.

네트리파이(Netlify)를 사용해 배포하기#

여러분의 도큐사우루스 2 사이트를 네트리파이(Netlify)에 배포하려면 먼저 아래와 같은 설정이 필요합니다.

docusaurus.config.js
module.exports = {  url: 'https://docusaurus-2.netlify.com', // URL에 트레일링 슬래시를 붙이지 않습니다.  baseUrl: '/', // 저장소에서 사이트 상대 경로 Base 디렉터리  // ...};

그리고나서 여러분의 사이트를 네트리파이에 만듭니다.

사이트 설정을 위해 다음과 같은 빌드 명령과 디렉터리를 지정해주세요.

  • 빌드 명령: npm run build
  • 빌드 디렉터리: build

사전에 빌드 옵션을 설정하지 않았더라도 사이트를 만든 이후에 "Site settings" -> "Build and deploy" 메뉴에서 설정할 수 있습니다.

위에 설명한 옵션으로 적절하게 설정했다면 여러분의 사이트를 배포할 수 있습니다. 그리고 기본적으로 master로 설정된 배포 브랜치에 병합되면 자동으로 재배포가 진행됩니다.

important

URL이 소문자로 변경되거나 불필요한 리다이렉트, 404 에러를 피하려면 네트리파이에서 Pretty URLs 설정을 비활성화해주어야 합니다.

베르셀(Vercel)을 사용해 배포하기#

도큐사우루스 프로젝트를 베르셀(Vercel)에 배포하면 성능과 사용 편의성 측면에서 몇 가지 이점이 제공됩니다.

베르셀 깃 통합 기능을 사용해 도큐사우루스 프로젝트를 배포하기 위해서는 깃 저장소에 제대로 업로드되었는지 확인합니다.

베르셀의 가져오기 기능을 이용해 프로젝트를 가져옵니다. 가져오기 시 미리 설정된 관련 옵션을 확인할 수 있습니다. 모든 옵션은 변경할 수 있으며 목록은 베르셀 가이드 문서에서 확인할 수 있습니다.

프로젝트를 가져온 후 브랜치로 보내지는 모든 작업에 대해 미리보기 배포가 만들어집니다. 그리고 제품 브랜치(보통 "main")에 변경이 생기면 제품 배포가 진행됩니다.

렌더(Render)를 사용해 배포하기#

렌더(Render)무료 사이트 호스팅 서비스를 제공합니다. SSL, 커스텀 도메인, 글로벌 CDN, 깃 저장소와 연동한 지속적인 자동 배포를 지원합니다. 렌더에서 도큐사우루스 배포하기 가이드를 참고하면 빠르게 시작해볼 수 있습니다.

Qovery를 사용해 배포하기#

Qovery는 여러분의 AWS, GCP, Azure 같은 디지털 바다 속의 여러 계정에서 동작하고 있는 정적 사이트, 백엔드 API, 데이터베이스, 크론잡, 기타 앱을 한 곳에서 관리할 수 있는 완전 관리형 클라우드 플랫폼입니다.

  1. Qovery 계정을 만듭니다.

계정이 없는 경우 Qovery 대시보드에서 계정을 만듭니다.

  1. 프로젝트를 만듭니다.

"Create a new project"를 클릭하고 프로젝트명을 설정합니다.

"Next"를 클릭합니다.

  1. 애플리케이션을 추가합니다.

"Create an application"을 클릭하고 "I have an application" 항목을 선택한 후 앱이 위치한 깃허브 또는 깃랩 저장소를 선택합니다.

"Next"를 클릭합니다.

서비스 추가하기는 생략합니다.

  1. 배포

"Deploy"를 클릭합니다.

클릭하면 배포 로그에서 실시간으로 상태를 확인할 수 있습니다.

Hostman을 사용해 배포하기#

Hostman은 정적 웹 사이트에 대한 무료 호스팅을 제공합니다. Hostman은 모든 것을 자동화로 지원합니다. 여러분은 저장소를 연결하고 간단한 단계를 따라오기만 하면 됩니다.

  1. 서비스를 만듭니다.

도큐사우루스 정적 웹 사이트를 배포하기 위해 Dashboard 상단 왼쪽 구석에 있는 Create 버튼을 클릭하고 Front-end app or static website 항목을 선택합니다.

  1. 배포할 프로젝트를 선택합니다.

깃허브, 깃랩, 비트버킷 계정으로 Hostman에 로그인했다면 개인 저장소를 포함해 여러분의 프로젝트가 있는 모든 저장소를 확인할 수 있습니다.

배포할 프로젝트를 선택합니다. 프로젝트 파일이 있는 디렉터리를 포함해야 합니다(보통 website 또는 my-website 디렉터리입니다).

다른 저장소에 접근하려면 Connect another repository 버튼을 클릭하세요.

로그인 시 깃 계정 인증을 거치지 않았다면 필요한 계정에 접근한 후 프로젝트를 선택할 수 있습니다.

  1. 빌드 설정을 구성한 다음에 Website customization 창이 표시됩니다.

Framework 목록에서 Static website 옵션을 선택하세요.

Directory with app 항목에 설정한 디렉터리가 빌드 후 프로젝트 파일이 포함되는 위치입니다. 두 번째 단계에서 콘텐츠 저장소로 website(또는 my_website) 디렉터리를 선택했다면 항목값을 채우지 않아도 됩니다.

도큐사우루스의 기본 빌드 명령을 실행합니다.

yarn run build

필요한 경우 빌드 명령을 변경할 수 있습니다. &&.로 구분해서 여러 개의 명령을 추가할 수 있습니다.

  1. Deploy 버튼을 클릭해서 빌드 프로세스를 시작합니다.

프로세스가 시작되면 배포 로그를 확인할 수 있습니다. 코드에 문제가 있다면 로그에서 경고나 에러 메시지를 확인하고 문제의 원인을 살펴볼 수 있습니다.

로그에는 디버깅에 필요한 모든 데이터를 담고 있습니다. 하지만 지원이 필요할 때는 언제든지 챗을 통해 문의해주시면 도움을 드릴 수 있습니다.

배포가 완료되면 이메일로 알림을 받을 수 있으며 로그에서도 확인할 수 있습니다.

완료되었습니다 !

여러분의 프로젝트를 공개할 준비가 끝났습니다.

서지(Surge)를 사용해 배포하기#

서지(Surge)는 웹 호스팅 플랫폼입니다. 명령행 도구를 사용해 간단하게 도큐사우루스 프로젝트를 배포할 수 있습니다. 여러분의 프로젝트를 서지에 배포하는 것은 쉽고 무료(커스텀 도메인과 SSL을 포함해)입니다.

다음 단계를 따라가면 서지를 사용한 앱 배포를 쉽게 할 수 있습니다.

  1. 먼저 npm 명령으로 서지를 설치합니다.
npm install --g surge
  1. 프로젝트 루트 디렉터리에서 사이트의 파일을 빌드하려면 아래 명령을 실행합니다.
npm run build
  1. 다음 명령어를 프로젝트 루트 디렉토리에서 실행하세요:
surge build/

서지를 처음 사용한다면 명령행에 계정을 만들라는 메시지가 표시됩니다(처음 한 번만 표시됩니다)

사이트가 build 디렉터리에 게시되면 *.surge.sh 서브도메인이 무작위로 만들어집니다(서브도메인은 수정할 수 있습니다).

가지고 있는 도메인 사용하기#

가지고 있는 도메인이 있다면 서지를 사용해 배포 시 명령에 도메인을 추가할 수 있습니다.

surge build/ yourdomain.com

여러분의 사이트는 선택에 따라 무료로 제공되는 subdomain.surge.sh 또는 yourdomain.com에서 운영할 수 있습니다.

CNAME 파일 설정하기#

다음 명령을 사용해 도메인을 CNAME 파일에 설정할 수 있습니다.

echo subdomain.surge.sh > CNAME

surge 명령을 사용해 이후 변경 사항 발생 시 배포를 진행할 수 있습니다.

퀀트CDN(QuantCDN)을 사용해 배포하기#

  1. 퀀트(Quant) CLI를 설치합니다.

  2. 퀀트CDN 계정을 생성합니다.

  3. quant init 명령으로 프로젝트를 초기화하고 여러분의 자격 정보를 설정합니다.

quant init
  1. 사이트를 배포합니다.
quant deploy

퀀트CDN을 사용한 배포 예제와 사용 사례는 가이드 문서블로그를 참고하세요.