GitHub Codespaces로 Quarto 워크숍을 더 쉽게 만드는 방법

GitHub Codespaces가 무엇인가요?

GitHub Codespaces는 브라우저 또는 GitHub Codespaces 확장을 통한 Visual Studio Code에서 실행할 수 있는 클라우드 기반 온디맨드 개발 환경입니다. 필수 종속성과 도구를 모두 갖춘 완전한 개발 컨테이너를 제공하므로 긴 로컬 설치 과정을 거치지 않아도 됩니다. 강사이든 개발자이든, 웹 브라우저에서 바로 각각의 프로젝트에 맞춰 일관된 환경으로 코딩을 시작할 수 있다는 의미입니다.

더 중요한 것은, 워크숍 참가자들도 GitHub Codespaces를 강사만큼 쉽게 사용할 수 있다는 점입니다. Codespaces를 사용하면 강사와 참가자 모두 같은 환경에서 작업하므로, “내 컴퓨터에서는 안 돼요”라는 문제를 최소화할 수 있습니다.

이 글에서는 서로 다른 노트북과 운영체제를 가진 참가자가 가득한 워크숍을 가정합니다. 물론 Codespaces는 개발 작업에도 유용하니, 이어지는 내용을 통해 그 이유를 확인해보세요.

Quarto CLI와 Codespaces를 함께 사용하는 이유

참가자들이 클라우드에서 모든 도구, 라이브러리, 샘플 프로젝트를 갖춘 동일한 환경을 즉시 사용할 수 있는 세상을 상상해보십시오. 그것이 바로 Codespaces를 활용하는 마법입니다:

즉각적인 도입: 워크숍 참가자나 학생은 번거로운 로컬 설정을 생략할 수 있습니다. 운영체제와 무관하게 원하는 웹 브라우저에서 Codespace를 실행하면 즉시 사전 구성된 환경이 준비됩니다.
일관된 환경: 모든 사람에게 동일한 도구와 종속성을 보장하는 일은 어렵습니다. Codespaces는 컨테이너 구성으로 환경을 미리 정의해 두어 소프트웨어 버전이나 설정의 차이를 줄여줍니다.
재현 가능한 워크플로: 데이터 과학 워크숍을 진행하든 연구 논문을 함께 작성하든 재현성은 핵심입니다. GitHub Codespaces는 Dev Container 규격을 따르므로, 모든 사람이 동일한 환경에서 코드를 실행할 수 있습니다. 참가자가 로컬에서 프로젝트를 실행할 준비가 되면, Codespace를 사용해 동일한 Docker 컨테이너를 만들 수 있습니다.

GitHub에서는 워크숍 참가자와 공유할 수 있는 Codespaces용 “딥 링크”를 제공합니다.

예를 들어 quarto-codespaces 저장소에는 여러 Dev Container/Codespaces 구성이 준비되어 있습니다. 다음 링크는 기본 .devcontainer/devcontainer.json 대신 .devcontainer/universal/devcontainer.json 구성 파일을 사용해 새 Codespace를 만듭니다.

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/mcanouil/quarto-codespaces?quickstart=1&devcontainer_path=.devcontainer%2Funiversal%2Fdevcontainer.json)

The link can include a specific branch, a particular file, or even a specific line in a file, allowing you to guide participants directly to the relevant content and setup. By doing nothing more than clicking that one link, participants create or resume an existing execution environment.

Quarto-Codespaces 환경 직접 구성하기

다음 워크숍이나 강의에서 Quarto CLI와 Codespaces를 함께 사용하고자 한다면, 다음과 같은 방식으로 시작할 수 있습니다.

quarto-codespaces 저장소의 예제를 활용하거나 기본 Codespaces를 직접 만들어 사용할 수 있습니다.

기존 Docker 이미지 활용

Quarto CLI와 필요한 종속성을 모두 갖춘 기존 Docker 이미지를 사용하는 것이 가장 간단한 시작법입니다. Quarto CLI 포함 여부에 따라 여러 가지 미리 빌드된 이미지가 있습니다:

Official Docker images:
- ghcr.io/quarto-dev/quarto
- ghcr.io/quarto-dev/quarto-full
Community Docker images:
- ghcr.io/mcanouil/quarto-codespaces
Default Codespaces image:
- mcr.microsoft.com/devcontainers/universal

이 이미지들 중 어느 것이든 Codespace의 베이스로 사용 가능합니다. .devcontainer/devcontainer.json 파일 내에서 사용할 이미지를 지정할 수 있습니다. .devcontainer/devcontainer.json은 Codespace를 위한 설계도 역할을 합니다.

{
  "name": "My Workshop Setup",
1  "image": "ghcr.io/mcanouil/quarto-codespaces:latest",
  "remoteUser": "vscode",
  "customizations": {
    "vscode": {
      "extensions": [
2        "quarto.quarto",
3        "mcanouil.quarto-wizard"
      ]
    },
    "codespaces": {
4      "openFiles": [
        "exercises/intro-to-quarto.qmd",
        "exercises/computation.qmd"
      ]
    }
  }
}

1: image 필드에서 Docker 이미지를 지정합니다. 이 이미지는 .github/.devcontainer에 있는 Dev Container 규격을 사용해 빌드됩니다.
2: Visual Studio Code/Positron용 quarto 확장으로 Quarto 문서 지원을 제공합니다.
3: Visual Studio Code/Positron용 quarto-wizard 확장으로 Quarto 확장 관리를 돕습니다.
4: openFiles 필드는 Codespace 생성 시 열어둘 파일을 지정합니다. 참가자에게 적절한 파일이나 폴더를 안내하는 데 유용하며, 자세한 내용은 Codespaces 문서를 참고하세요.

개발 컨테이너 구성하기

자신만의 Codespaces를 위해 quarto-codespaces 저장소를 포크하는 것으로 시작할 수 있습니다. 이 저장소에는 Quarto CLI와 필수 도구를 포함한 환경 설정을 Codespaces에 지시하는 Dev Container 구성 파일(즉, .devcontainer/devcontainer.json)이 포함되어 있습니다.

.devcontainer/devcontainer.json은 Quarto CLI 버전부터 필요한 라이브러리나 확장까지 모든 요소를 포착해 Codespace의 모든 인스턴스를 동일하게 유지하도록 보장합니다.

또한 quarto-codespaces 저장소는 최신 Quarto CLI, Python, R, Julia가 설치된 사전 빌드 Docker 이미지를 제공하므로 훌륭한 출발점입니다(예: .github/.devcontainer/devcontainer.json을 사용하는 ghcr.io/mcanouil/quarto-codespaces).

{
  "name": "Quarto",
1  // "image": "buildpack-deps:jammy-curl",
  "build": {
    "dockerfile": "./Dockerfile",
    "context": ".",
    "args": {
      "VARIANT": "jammy"
    }
  },
  "remoteUser": "vscode",
2  "features": {
3    "./quarto-computing-dependencies": {
      "rDeps": "rmarkdown,languageserver,nx10/httpgd@v2.0.3,prompt,lintr",
      "pythonDeps": "jupyter,papermill",
      "juliaDeps": "IJulia"
    },
4    "./uv": {
      "version": "latest"
    },
5    "ghcr.io/rocker-org/devcontainer-features/quarto-cli:1": {
      "version": "release",
      "installTinyTex": "true",
      "installChromium": "false"
    }
  },
6  "customizations": {
    "vscode": {
      "extensions": [
        "quarto.quarto",
        "mcanouil.quarto-wizard",
        "REditorSupport.r",
        "Posit.air-vscode"
      ],
      "settings": {
        "r.rterm.option": [
          "--no-save",
          "--no-restore-data",
          "--quiet"
        ],
        "[r]": {
          "editor.defaultFormatter": "Posit.air-vscode",
          "editor.formatOnSave": true
        }
      }
    }
  }
}

1: image 필드는 컨테이너의 베이스 이미지를 지정합니다. 필요에 따라 이 값을 커스터마이즈할 수 있습니다.
2: features 섹션에서는 추가 도구나 라이브러리를 넣을 수 있습니다. 이용 가능한 기능 목록은 Dev Container Features를 참고하세요.
3: quarto-computing-dependencies 기능은 R, Python, Julia 등 계산 종속성을 설치하는 로컬 커스텀 기능입니다. Quarto 문서를 실행하는 데 필요한 모든 요소를 Codespace에 확보하는 좋은 방법입니다.
4: uv 기능은 Python 패키지와 프로젝트 종속성을 관리하는 uv 도구를 설치합니다.
5: quarto-cli 기능은 Quarto CLI를 설치합니다. 설치하고자 하는 버전을 지정하면 Codespace 내에서 자동으로 다운로드되고 설치됩니다. 이 기능의 코드는 https://github.com/rocker-org/devcontainer-features/tree/main/src/quarto-cli에서 확인할 수 있습니다.
6: customizations 섹션에서는 Visual Studio Code용 설정과 확장을 지정할 수 있습니다.

필요에 따라 devcontainer.json에 기능을 추가하거나, 앞서 설명한 기존 Docker 이미지 활용처럼 이미지를 그대로 사용할 수도 있습니다.

예를 들어 R 패키지나 Python 라이브러리를 추가로 설치하고자 하는 경우, quarto-computing-dependencies 커스텀 기능의 rDeps, pythonDeps, juliaDeps 필드를 원하는 패키지 목록으로 바꾸거나, postStartCommand 항목에서 필요한 패키지 설치 스크립트를 실행하도록 설정할 수 있습니다.

{
  "name": "My Workshop Setup",
  "image": "ghcr.io/mcanouil/quarto-codespaces:latest",
  "remoteUser": "vscode",
  "postStartCommand": "uv venv && source .venv/bin/activate && uv pip install -r requirements.txt"
}

postStartCommand 항목에서도 필요한 패키지를 설치하는 스크립트를 실행할 수 있습니다.

{
  "name": "My Workshop Setup",
  "image": "ghcr.io/mcanouil/quarto-codespaces:latest",
  "remoteUser": "vscode",
1  "postStartCommand": "bash ./init-env.sh --what all --force"
}

1: postStartCommand 필드는 Codespace가 시작된 후 실행할 명령을 지정합니다. 위 예에서는 quarto-codespaces 저장소의 init-env.sh 스크립트를 --what all과 --force 옵션과 함께 실행합니다.

워크숍과 교육에서의 이점

교육 세션에서는 일관성과 사용 편의성이 가장 중요합니다. Codespaces와 Quarto CLI의 조합은 교육 환경에서 여러 가지 직접적인 이점을 제공합니다:

간편한 도입: 학생과 워크숍 참가자는 로컬 환경을 설치하고 구성하는 데 시간을 들이지 않고 바로 작업을 시작할 수 있습니다.
실시간 상호작용 세션: 강사는 Quarto 문서를 실시간으로 수정하면서 시연할 수 있습니다. 변경 사항은 즉시 렌더링되어 각 참가자의 환경에 반영되므로 실습 중심의 상호작용 학습에 적합합니다.
협업과 버전 관리: 모든 변경 사항은 Git으로 기록되어 진행 상황 추적, 피어 리뷰, 공동 작업을 단일 호스트 환경에서 쉽게 관리할 수 있습니다.
종속성 문제 제거: 컨테이너화된 개발 환경으로 모든 참가자가 동일한 기준으로 작업하므로 버전 충돌이나 라이브러리 누락으로 세션이 중단되는 일을 방지합니다.

마무리 생각과 향후 방향

워크숍을 진행하든 수업을 가르치든 연구 협업을 하든, Codespaces를 활용하면 설정의 번거로움을 줄이고 재현성을 높이며 상호작용적인 학습을 장려할 수 있습니다.

앞서 언급한 이점 외에도 Codespaces와 Quarto CLI를 함께 사용할 때 경험을 더 풍부하게 만드는 기능들이 있습니다:

자동화 파이프라인: 정확히 동일한 환경에서 Quarto 문서 렌더링을 자동으로 검증하고 오류를 잡기 위해 CI/CD 도구를 통합합니다. 자세한 내용은 GitHub Actions: Running jobs in a container를 참고하세요.
실시간 공동 편집 기능: Codespaces에서 동시에 여러 사용자가 편집하는 기능으로 협업 세션을 강화합니다. 자세한 내용은 GitHub Codespaces: Real-time collaboration에서 확인할 수 있습니다.

이 글은 Codespaces와 Quarto를 함께 사용하는 기본을 다뤘지만, Codespaces에는 훨씬 더 많은 가능성이 있습니다. 공식 문서를 참고해 더 알아보세요.

즐거운 교육 되세요!

면책 사항

GitHub Codespaces는 GitHub, Inc.의 제품으로 CPU 시간과 저장소 등 무료 사용량이 정해져 있습니다. 예상치 못한 요금이 발생하지 않도록 GitHub Codespaces 요금 문서와 현재 GitHub 요금제를 꼭 확인하세요. 학생이나 교육자라면 GitHub Education 프로그램과 GitHub Classroom을 살펴보는 것도 좋습니다.

감사의 말

이 글에 대한 피드백과 제안을 주신 Carlos Scheidegger, Julia Silge, James J. Balamuta께 감사드립니다.