Netlify

개요

Netlify는 사용자 정의 도메인, 인증, 브랜치 미리보기, 즉시 롤백 등 다양한 고급 기능을 지원하는 전문 웹 배포 플랫폼입니다. 개인 프로젝트, 취미 사이트, 실험에 적합한 무료 플랜도 제공합니다.

Quarto 콘텐츠를 Netlify에 배포하는 방법은 여러 가지가 있습니다.

로컬에서 렌더링한 콘텐츠를 quarto publish 명령으로 배포
GitHub, GitLab, Bitbucket, Azure DevOps를 사용한다면 사이트 소스 코드를 Netlify에 연결해 코드 변경 시마다 배포
GitHub을 사용한다면 GitHub Action으로 코드 변경 시마다 프로젝트를 자동 렌더링하고 결과를 배포
다른 CI(Continuous Integration) 서비스를 사용한다면 quarto publish 명령을 스크립트로 구성해 Netlify에 렌더링 및 배포

아래에서 가장 간단한 방법부터 더 고급 시나리오까지 차례대로 다룹니다.

배포 명령

quarto publish 명령은 로컬에서 렌더링한 콘텐츠를 배포하는 가장 쉬운 방법입니다. 프로젝트가 있는 디렉터리에서 Netlify용 quarto publish 명령을 실행하세요.

Terminal

quarto publish netlify

Netlify에 이전에 배포한 적이 없다면 배포 명령이 인증을 요청합니다. 배포를 진행한다고 확인하면 콘텐츠가 렌더링되고 배포되며, 브라우저가 열려 사이트를 확인할 수 있습니다.

_publish.yml

_publish.yml 파일은 배포 대상을 지정하는 데 사용됩니다. 이 파일은 quarto publish 명령을 실행할 때마다 자동으로 생성(또는 업데이트)되며, 프로젝트 또는 문서 디렉터리에 위치합니다.

배포된 콘텐츠의 서비스, id, URL은 _publish.yml에 지정됩니다. 예:

- source: project
  netlify:
    - id: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://tubular-unicorn-97bb3c.netlify.app"

이미 배포하려는 Netlify 사이트가 있다면 위 예시와 같은 _publish.yml 파일을 수동으로 만들고, 사이트에 맞는 id와 url 값을 넣어야 합니다.

계정 정보는 _publish.yml에 저장되지 않으므로 버전 관리에 포함하거나 여러 배포자가 공유해도 안전합니다.

옵션

다음 명령줄 옵션으로 quarto publish의 동작을 사용자 지정할 수 있습니다.

옵션	동작
`--no-prompt`	배포 확인 프롬프트를 표시하지 않습니다.
`--no-browser`	배포 후 브라우저를 열지 않습니다.
`--no-render`	배포 전에 다시 렌더링하지 않습니다.

웹사이트나 책이 아닌 문서를 배포하려면 문서 경로를 지정하세요.

Terminal

quarto publish netlify document.qmd

도메인 이름

배포된 사이트의 도메인 이름은 기본적으로 임의 식별자(예: mystifying-jepsen-fa4396.netlify.app)를 사용합니다. 더 설명적인 서브도메인(netlify.app를 유지)을 선택하거나, 별도 도메인을 소유하고 있다면 해당 도메인을 사이트에 할당할 수 있습니다. 이 옵션은 각각 Site settings, Domain settings에서 설정합니다.

Site settings에서 Change site name 버튼을 클릭해 다른 서브도메인을 지정하세요.

별도 도메인을 사용하려면 Domain settings의 안내를 따르세요.

Git 제공자에서 배포

Netlify는 GitHub, GitLab, Bitbucket, Azure DevOps에 호스팅된 Git 저장소에 변경이 커밋되면 자동으로 사이트를 배포할 수 있습니다. 가장 간단한 방법은 렌더링된 사이트(_site 또는 _book 디렉터리)를 버전 관리에 포함하고 Netlify가 이를 배포하게 하는 것입니다. 먼저 이 시나리오를 다룬 다음 Netlify 빌드 플러그인으로 Netlify 서버에서 렌더링하는 방법을 살펴봅니다.

프로젝트 가져오기

팀의 Netlify 메인 페이지로 이동해 Add new site를 선택한 다음 Import an existing project를 클릭하세요.

버전 관리 제공자 인증, 저장소 선택, 배포 설정 입력을 순서대로 진행합니다.

배포 구성

프로젝트의 빌드 설정은 Build command를 비워 두고 Publish directory에 _site 또는 _book(적절한 것)을 지정합니다.

_site 또는 _book 디렉터리를 버전 관리에 포함했다면 설정은 완료되며, 저장소에 커밋할 때마다 Netlify가 자동으로 배포합니다.

Netlify에서 렌더링

렌더링된 사이트를 버전 관리에 포함하고 싶지 않다면 Quarto Netlify 빌드 플러그인으로 Netlify 빌드 서버에서 렌더링할 수 있습니다(단, Netlify 서버는 마크다운만 렌더링하며 R/Python/Julia 코드는 실행할 수 없음).

Freezing Computations

R, Python, Julia 코드가 로컬에서만 실행되도록 하려면 _quarto.yml에 다음을 추가해 Quarto의 freeze 기능을 사용하도록 프로젝트를 구성하세요.

_quarto.yml

execute:
  freeze: auto

이제 사이트를 완전히 다시 렌더링하세요.

Terminal

quarto render

프로젝트에 실행 가능한 코드가 있으면 최상위에 _freeze 디렉터리가 생성됩니다. 이 디렉터리는 계산 결과를 저장하며 버전 관리에 포함해야 합니다. 실행 가능한 코드가 있는 .qmd 파일을 변경하면 다음 렌더링에서 자동으로 다시 실행되고, 업데이트된 계산 결과가 _freeze에 저장됩니다.

Ignoring Output

_site 또는 _book 디렉터리는 버전 관리에 포함할 필요가 없습니다(이전에 포함해 봤다면 매우 지저분한 diff가 생긴다는 것을 알 것입니다!). 진행하기 전에 프로젝트의 출력 디렉터리를 .gitignore에 추가하세요. 예:

.gitignore

/.quarto/
/_site/

이미 이 파일들을 버전 관리에 포함했다면 명시적으로 제거해야 할 수도 있습니다.

Terminal

git rm -r _site

플러그인 구성

To use the Quarto Netlify Build Plugin, add the following two files to your project:

netlify.toml

[[plugins]]
package = "@quarto/netlify-plugin-quarto"

package.json

{
  "dependencies": {
    "@quarto/netlify-plugin-quarto": "^0.0.5"
  }
}

이제 수정된 프로젝트(_freeze, netlify.toml, package.json 포함)를 커밋하고 푸시하세요. 이전 단계에서 프로젝트를 올바르게 설정했다면(즉, Publish directory를 _site 또는 _book로 설정) 새 커밋을 푸시할 때마다 Netlify가 렌더링과 배포를 시작합니다.

GitHub Action

quarto publish netlify 명령으로 로컬에서 렌더링한 콘텐츠를 배포하는 것이 가장 간단하고 직관적인 방법입니다. 또 다른 방법은 GitHub Actions를 사용해 사이트를 렌더링하고 배포하는 것입니다(커밋으로 실행 및/또는 렌더링이 자동으로 트리거되길 원한다면 이 방법을 선호할 수 있습니다).

렌더링과 배포에는 여러 접근 방식이 있습니다. 아래에서는 GitHub Actions로 배포하는 방법을 안내합니다. 다양한 접근 방식의 개념적 배경은 CI 렌더링에서 확인하세요.

배포 기록

GitHub Action으로 배포하기 전에 배포 명령(바로 위에서 설명)으로 최소 한 번 배포를 완료해야 합니다. 이 배포 과정에서 GitHub Action이 사용할 배포 대상을 기록하는 _publish.yml 파일이 생성됩니다. 예:

- source: project
  netlify:
    - id: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://tubular-unicorn-97bb3c.netlify.app"

위 예시와 같은 _publish.yml 파일을 수동으로 만들고 사이트에 맞는 id와 url 값을 넣어도 됩니다.

배포 대상을 나타내는 _publish.yml 파일이 준비되기 전에는 다음 단계로 진행하지 마세요.

계산 동결

R, Python, Julia 코드가 로컬에서만 실행되도록 하려면 _quarto.yml에 다음을 추가해 Quarto의 freeze 기능을 사용하도록 프로젝트를 구성하세요.

_quarto.yml

execute:
  freeze: auto

이제 사이트를 완전히 다시 렌더링하세요.

Terminal

quarto render

대안으로 GitHub Action에서 코드를 실행하는 방법도 있습니다. 지금은 로컬에서 코드를 실행하고 freeze로 계산 결과를 저장하는 방식으로 단순화합니다. 이후에 GitHub Action에서 코드 실행하는 방법을 설명합니다.

배포 액션

다음 YAML 파일을 만들어 .github/workflows/publish.yml에 저장해 publish.yml GitHub Action을 프로젝트에 추가하세요.

.github/workflows/publish.yml

on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4 

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Render and Publish 
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: netlify
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

Netlify 자격 증명

마지막 단계는 Netlify 배포에 필요한 자격 증명을 GitHub Action에 설정하는 것입니다. Netlify 개인 액세스 토큰을 만들고 GitHub Action이 이를 읽을 수 있도록 구성해야 합니다.

액세스 토큰이 없다면 Netlify applications 페이지로 이동해 New Access Token을 클릭하여 새 개인 액세스 토큰을 생성하세요. 기억하기 쉬운 이름을 지정하고 토큰을 클립보드에 복사합니다.
Netlify 개인 액세스 토큰을 저장소의 액션 Secrets(저장소 Settings에서 접근)로 추가합니다. 오른쪽 상단에 New repository secret 버튼이 있습니다.

버튼을 클릭하고 1단계의 개인 액세스 토큰을 NETLIFY_AUTH_TOKEN 이름의 secret으로 추가하세요.

Ignoring Output

.gitignore

/.quarto/
/_site/

이미 이 파일들을 버전 관리에 포함했다면 명시적으로 제거해야 할 수도 있습니다.

Terminal

git rm -r _site

커밋으로 배포

배포 액션과 Netlify 자격 증명을 지정하고 _freeze 디렉터리를 포함한 업데이트된 저장소를 GitHub에 푸시하면, 이 커밋과 이후 커밋에서 액션이 실행되어 Netlify에 자동으로 렌더링 및 배포됩니다.

코드 실행

원한다면 GitHub Action에서 렌더링의 일부로 R, Python, Julia 코드를 실행하도록 구성할 수도 있습니다. 직관적으로 최선처럼 보일 수 있지만, GitHub Actions 같은 CI 서비스에서 코드를 실행할 때는 다음 요구 사항을 고려해야 합니다.

CI 환경에서 모든 의존성(R, Python, Julia 및 필요한 패키지의 정확한 버전)을 재현해야 합니다.
코드가 특별한 권한(예: 데이터베이스 또는 네트워크 접근)을 요구한다면 해당 권한도 CI 서버에 있어야 합니다.
프로젝트에는 더 이상 쉽게 실행할 수 없는 문서(예: 오래된 패키지 버전을 사용하는 몇 년 전 블로그 글)가 있을 수 있습니다. 이런 문서는 CI에서 실행되지 않도록 개별적으로 freeze를 활성화해야 할 수 있습니다.

사전 준비

GitHub Action에서 코드가 실행되도록 보장하는 가장 좋은 방법은 프로젝트에서 venv나 renv 같은 가상 환경을 사용하는 것입니다(아래에서 각각의 예시 액션을 제공합니다). 이러한 도구 사용이 익숙하지 않다면 Quarto에서 가상 환경을 사용하는 문서를 참고하세요.

GitHub Action에서 코드를 실행하기로 결정했다면 _quarto.yml에서 위에서 설명한 freeze: auto를 제거할 수 있습니다. 일부 문서나 디렉터리에서 선택적으로 freeze를 사용하는 것은 여전히 가능합니다(디렉터리의 경우 해당 디렉터리에 _metadata.yml 파일을 만들고 freeze 구성을 지정하면 됩니다. 이는 Quarto가 블로그 프로젝트의 posts 폴더에서 기본으로 하는 방식입니다).

예시: venv와 Jupyter

다음은 requirements.txt에서 Python, Jupyter, 패키지 의존성을 설치한 뒤 코드를 실행하고 Netlify에 출력물을 렌더링하는 GitHub Action의 완전한 예시입니다.

.github/workflows/publish.yml

on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4 

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        
      - name: Install Python and Dependencies
        uses: actions/setup-python@v5
        with:
          python-version: '3.10'
          cache: 'pip'
      - run: pip install jupyter
      - run: pip install -r requirements.txt
      
      - name: Render and Publish 
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: netlify
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

예시: renv와 Knitr

다음은 renv.lock에서 R과 패키지 의존성을 설치한 뒤 코드를 실행하고 Netlify에 출력물을 렌더링하는 GitHub Action의 완전한 예시입니다.

.github/workflows/publish.yml

on:
  workflow_dispatch:
  push:
    branches: main

name: Quarto Publish

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4 

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2
        
      - name: Install R
        uses: r-lib/actions/setup-r@v2
        with:
          r-version: '4.2.0'
      
      - name: Install R Dependencies 
        uses: r-lib/actions/setup-renv@v2
        with:
          cache-version: 1
      
      - name: Render and Publish
        uses: quarto-dev/quarto-actions/publish@v2
        with:
          target: netlify
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

추가 옵션

더 큰 GitHub 저장소에서 Quarto 프로젝트가 최상위 디렉터리에 있지 않을 수도 있습니다. 이 경우 publish 액션 호출에 path 입력을 추가하세요. 예:

- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: netlify
    path: subdirectory-to-use
    NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

기본적으로 quarto publish는 배포 전에 프로젝트를 다시 렌더링합니다. 그러나 렌더링된 출력을 버전 관리에 저장한다면 GitHub Action이 다시 렌더링할 필요가 없습니다. 이 경우 publish 액션에 render: false 옵션을 추가하세요.

- name: Render and Publish
  uses: quarto-dev/quarto-actions/publish@v2
  with:
    target: netlify
    render: false
    NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

지속적 통합

어떤 CI 서비스든 quarto publish 명령을 스크립트로 구성해 Netlify에 Quarto 콘텐츠를 배포할 수 있습니다.

예를 들어 다음은 프로젝트 루트의 _publish.yml 파일 정보를 기반으로 Netlify에 배포하는 셸 스크립트입니다.

Terminal

# credentials from https://app.netlify.com/user/applications
export NETLIFY_AUTH_TOKEN="45fd6ae56c"

# publish to the netlify site id provided within _publish.yml
quarto publish netlify

_publish.yml의 내용은 다음과 같습니다.

- source: project
  netlify:
    - id: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://tubular-unicorn-97bb3c.netlify.app"

다음은 명령줄에서 배포 대상을 지정하는 다른 변형입니다.

Terminal

quarto publish netlify --id 5f3abafe-68f9-4c1d-835b-9d668b892001

렌더링과 배포에 대한 다양한 접근 방식은 CI로 배포 문서를 참고하세요.