JupyterLite + GitHub Pages

computer-tool
coding
인스톨이 필요 없는 주피터 노트북!
Author

JS HUHH

Published

December 6, 2022

TL; DR

  • 인스톨 없이 주피터 노트북을 사용할 수 있다굽쇼?

Not in this Post

  • Jupyter, jupyterlite에 대해서 상세히 다루지 않는다.
  • Github Pages에 대해서 상세히 다루지 않는다.

What in this Post

  • 별도의 인스톨 없이 손 쉽게 웹 브라우저에서 Jupyter 코딩 환경을 구현하는 JupyterLite를 소개한다.
  • jupyterLite를 github pages에 올리는 방법을 다룬다.

Jupyterlite

보통 파이썬 작업을 하기 위해서는 사전 설치가 필요하다. 아마도,

  1. 로컬 PC에 필요한 소프트웨어를 설치한다.
  2. 원격 PC에 필요한 소프트웨어를 설치하고, 여타 클라이언트(주로 웹 브라우저)에서 접속해 활용한다.

두 가지 방법 모두 소프트웨어를 어딘가에 까는 과정이 포함된다.

가끔은 ’공통 환경’이 필요할 때가 있다. 강의나 구현물의 시현을 해야 한다면 동일한 결과를 얻는 것이 필요하다. 결과물을 얻은 컴퓨터를 사용하거나 원격 접속을 설정하지 않고 이러한 수준의 공동 환경을 만들 수 있을까? 즉 .ipynb, .py 등의 파일을 교환하는 수준을 넘어선 ’호환성’을 게으르고 편리하게 보장할 수 있을까?

만일 웹 브라우저만 구동해서 이 공통 환경을 빠르게 만들어낼 수 있다면 어떨까? 이를 실현한 것이 jupyterLite이다.

주피터라이트는 가벼운 노트북 환경을 구현하는 것을 목표로 한다. 이 녀석은 아직 시험 단계의 프로젝트지만 많은 주목을 받고 있다. 이때 ’가벼운 노트북’이란 주피터 환경을 구현하는 데 있어 웹 브라우저와 단순한 스태틱 웹 페이지 이외에 어떤 것도 필요하지 않다는 뜻이다.

웹어셈블리(WASM)로 구현된 파이썬 인터프리터를 통해서 브라우저만 있으면 아주 단순한 웹 페이지 하나로 주피터라이트가 파이썬과 주피터(IDE)의 마법을 부린다. 원래 주피터 노트북이라는 녀석이 서버-클라이언트를 전제로 만들어진 것인데, 여기서 서버가 빠진 가벼운 변종이 주피터라이트다.

패키지 설치

여기까지 들으면 ‘웹 브라우저에서 도는 것은 좋은데 패키지 설치는 가능해?’ 라고 묻고 싶어질 터. 답부터 말하면, 가능하지만 전부 가능한 것은 아니다. ’일반적’으로 많이 쓰는 패키지인 pandas, numpy, scipy, scikit-learn 등은 거의 주피터라이트 위에 쉽게 올라간다. 대단한 복잡도를 지닌 앱이 아니라 개념을 입증하는 프로토타입 특히 교육용으로 주피터를 쓰려는 용도라는 주피터라이트로 충분하다.

패키지 설치는 주피터 노트북에서 매직 코멘트(%)를 활용한다. 예를 들어 python %pip install koreanize-matplotlib 한 가지 주의 사항 확인하자. 루트 디렉토리에 있는 requirements.txt에 속지 말자. 이 녀석은 jupyterlab, jupyterlite 그리고 두 개에 필요한 요소를 설치하기 위한 파일이다. 주피터라이트 내에서 돌아가는 파이썬 패키지 설치와는 무관하다. 주피터라이트는 WASM으로 브라우저 안에서 독립적으로 구현된 IDE 환경이다.

직접 체험해보시는 편이 훨씬 낫다; JupyterLite

위의 예에서 보듯이 노트북의 UI로는 주피터랩(기본), 레트로, REPL(Read-Evaluate-Print Loop)를 자유롭게 쓸 수 있다.

Github Pages

이제 이렇게 만들어진 페이지를 웹을 통한 전달할 경로가 필요하다. 만일 별도로 서버를 복잡하게 세팅해야 한다면 주피터라이트의 장점도 거의 사라질 것이다.

웹어셈블리는 css, js만 사용한다. 이는 스태틱 웹을 통해서도 주피터라이트가 돌아간다는 의미이다. 그리고 스태틱 웹을 호스팅하는 현존하는 가장 저렴하고 편리한 방식은 GitHub Pages다.

테스트로 빌드한 리포는 여기를 참고하자. python-notebooks 디렉토리가 포함되어 있는데, 여기 matplotlib 한글을 구현하는 노트북 등 몇 가지 활용에 참고할 만한 간단한 예제를 넣어 두었다.

빌드하고 연동하는 방법이 공식 페이지에 잘 소개되어 있다. 호스팅을 위해서는 GitHub Actions를 통한 빌드의 과정이 필요한데, 이용자가 크게 신경 쓸 것은 없다. 소개된대로 템플릿을 가져와서 사용하면 된다. 해당 리포의 변형이 있을 떄마다 푸시를 하면 Actions를 통한 build -> Pages를 통한 depoly 과정이 자동으로 발생한다. 주의 사항만 몇가지 적어두자.

  • Settings > General에서 “Danger Zone”
    • “Change repository visibility”를 “public”으로 설정
    • Pro 회원이라면 Private 상태에서도 Pages를 호스팅할 수 있다. 일반 회원의 경우 소스가 공개되어 있어야 Pages 호스팅이 가능하다.
  • Settings > (왼쪽 탭에서) GitHub Pages에서
    • “Build and deployment” 항목
    • “Source”를 “Github Actions”로 설정하도록 하자.

설정은 이게 전부이다. 빌드가 잘 되었는지 확인하기 위해서는 상단 탭에서 “Actions”를 선택하자. 빌드가 진행중인지 끝났는지를 확인할 수 있을 것이다. 발드가 끝났다면, 이제 Pages를 방문하도록 하자. 주소는 아래와 같다.

GitHub Pages 주소 
{이용자-깃헙계정}.github.io/{이용자-리포이름}

👉http://anarinsk.github.io/demo_jupyterlite

자세히 들여다 본 빌드 과정

깃허브 디렉토리의 감춰진 디렉토리를 보이게 설정하자. 해당 디렉토리 안에 .github/workflows로 들어가면 deploy.yml이 있다. 이 녀석이 깃허브 액션스의 빌드 순서 및 명렁을 구성한다. 내용을 전부 설명할 필요는 없다. 필요한 부분만 살펴보자.

- name: Setup Python
    uses: actions/setup-python@v4
    with:
        python-version: '3.10'
- name: Install the dependencies
    run: |
        python -m pip install -r requirements.txt
- name: Build the JupyterLite site
    run: |
        cp README.md content
        jupyter lite build \
            --XeusPythonEnv.packages=scikit-learn,matplotlib,pandas,plotly,ipywidgets,openpyxl \
            --contents content --output-dir dist
- name: Upload artifact
    uses: actions/upload-pages-artifact@v1
    with:
        path: ./dist
Code Tips
  • -name: | 액션스를 행동을 구분하는 단위의 이름을 지정한다.
  • -name: Setup Python | 깃헙 리포에서 파이썬을 쓰겠다고 선언한다. 버전도 구별할 수 있다.
  • -name: Install the dependencies | 빌드를 위한 파이썬 관련 패키지 설치
  • -name: Build the JupyterLite site | jupyterlite를 빌드한다. 빌드 명령어는 jupyter lite build...에서 확인항 수 있다.
    • 이 명령은 기본으로 pyodide 기반의 pyolite 파이썬 커널을 설치한다.
    • XeusPythonEnv.packages= | xeus-python 커널이 추가로 설치되며, 해당 커널에 필요한 패키지를 올린다. 공식 페이지 절차대로 템플릿을 복사해서 썼다면 이 대목이 없을 것이다. 필요하면 deploy.yml에 추가하면 된다.
    • --contents content | 빌드에 사용할 노트북 파일이 들어있는 디렉토리를 지정한다.
    • --output-dir dist | 빌드 결과물이 저장될 디렉토리를 지정한다.

별도로 로컬에서 빌드할 때와 명령어 자체는 동일하다. 그 앞 뒤로 깃허브 액션스에 맞는 설정이 들어간다고 보면 되겠다.

GitHub Actions 없이 빌드하고 싶다면?

가능하다. 그리 어렵지도 않다. 아래 링크를 참고하자.

https://github.com/anarinsk/test_jupyterlite-build

몇 가지 더

커널 관련(outdated)

위 빌드 과정에서 보듯이 두 개의 파이썬 커널을 설치했다. 범용성은 pyodide 기반의 pyolite 커널이 낫다. 다만 네트워크 기능을 제대로 쓰기 위해서는 xeus-python이 편리하다. 예를 들어 scikit-learn 패키지에서 데이터를 인터넷으로 끌어오는 fetch 계열의 명령은 XePython 커널에서 제대로 작동한다. pyolite는 네트워크를 네이티브 파이썬 환경처럼 다루지 않는다.

네트워크와 관련한 보다 상세한 내용은 여기를 참고하도록 하자.

커널 관련(updated)

꼭 xeus-python을 써야 하나 싶다. Python의 네트워크 관련 명령들이 pyodide-http 패키지로 거의 완전하게 해결이 된다. 이 패키지는 기존 명령어를 주피터라이트에 맞게 패치한다. 아래 코드를 참고하자.

%pip install -q pyodide-http
import pyodide_http 
pyodide_http.patch_all() # 기존 http 관련 명령어 패치

pyodide에 관한 보다 상세한 내용은 해설 1, 해설 2를 참고하도록 하자.

몇 가지 핵심 활용법

content/python-notebooks 안에 믾이 쓸 것 같은 필요한 활용 용례를 몇 가지 넣어 두었다. 자세한 것은 README를 참고하면 된다.