정적 HTML과 GitHub Pages 게시
지금까지 서버 배포(Ch 01, Ch 04)와 WASM 내보내기(Ch 02, Ch 03)를 살펴봤습니다. 이 챕터에서는 내보낸 결과물을 GitHub Pages에 올려 누구든 URL 하나로 접근할 수 있게 하는 절차를 다룹니다.
그 전에 먼저 내보내기 형식을 하나 더 살펴봅니다. html-wasm과는 다른, 순수 정적 HTML을 만드는 html 형식입니다.
정적 HTML 내보내기
marimo export html notebook.py -o notebook.html이 명령은 노트북을 실행해 현재 출력을 캡처한 정적 HTML을 만듭니다. 결과물에는 Pyodide가 포함되지 않습니다. Python 코드가 실행된 결과물을 HTML로 스냅샷한 것이기 때문입니다.
# 출력(셀 실행 결과)을 포함하는 경우marimo export html notebook.py -o notebook.html# Jupyter와의 연동 — ipynb로 내보내기 후 변환하는 방식도 있음marimo export ipynb notebook.py -o notebook.ipynb --include-outputs정적 HTML의 특징은 위젯 조작이 불가능하다는 것입니다. 슬라이더를 드래그해도 값이 바뀌지 않습니다. Python이 브라우저에서 실행되지 않기 때문입니다. 대신 노트북을 실행한 시점의 결과를 보관하거나 공유할 때 유용합니다. 보고서나 결과물을 이메일로 첨부하거나 회의 자료로 내보낼 때 쓰기 좋습니다.
html vs html-wasm 비교
두 형식을 나란히 비교해 선택 기준을 명확히 합니다.
| 항목 | html (정적) |
html-wasm (WASM) |
|---|---|---|
| 위젯 조작 | 불가 | 가능 |
| Python 실행 | 사전 실행 결과만 | 브라우저에서 실행 |
| 파일 크기 | 작음 | 큼 (Pyodide 포함) |
| 서버 요건 | 없음 | HTTP 서빙 필요 |
| 패키지 제약 | 없음 | Pyodide 지원 패키지만 |
| 용도 | 보고서·결과 배포 | 인터랙티브 앱 배포 |
인터랙티브 기능이 필요하다면 html-wasm, 실행 결과를 정적으로 공유하는 것이 목적이라면 html을 선택합니다.
GitHub Pages 게시 절차
WASM으로 내보낸 결과물을 GitHub Pages에 게시합니다. GitHub Pages는 정적 파일을 HTTP로 서빙해 줍니다. Ch 02에서 WASM 파일은 반드시 HTTP로 서빙해야 한다고 했습니다. GitHub Pages가 그 조건을 자연스럽게 만족시킵니다.
1단계: 저장소 준비
GitHub에 저장소를 만들거나 기존 저장소를 사용합니다. GitHub Pages는 공개 저장소에서 무료로 사용할 수 있습니다.
2단계: WASM 결과물 생성
# 저장소 루트 또는 docs 디렉토리에 내보내기marimo export html-wasm notebook.py -o docsdocs 디렉토리에 내보내는 것은 GitHub Pages 설정과 맞추기 위해서입니다. GitHub Pages는 main 브랜치의 루트(/) 또는 docs 디렉토리를 배포 소스로 선택할 수 있습니다.
내보내기가 완료되면 docs 디렉토리 안에 index.html과 관련 파일들이 생성됩니다.
3단계: 저장소에 푸시
git add docs/git commit -m "docs: WASM 내보내기 결과물 추가"git push origin main4단계: GitHub Pages 활성화
GitHub 저장소 페이지에서 Settings를 클릭합니다. 왼쪽 메뉴에서 Pages를 선택합니다. Build and deployment 섹션에서 Source를 Deploy from a branch로 설정하고, Branch를 main, 디렉토리를 /docs로 선택합니다. Save를 클릭합니다.
잠시 기다리면 게시 URL이 표시됩니다. 보통 https://사용자명.github.io/저장소명/ 형태입니다.
5단계: 접근 확인
제공된 URL을 브라우저에서 엽니다. Pyodide 초기화 후 노트북이 실행됩니다. 위젯이 있다면 조작해 반응을 확인합니다.
Cloudflare Pages 배포
GitHub Pages 외에 Cloudflare Pages도 정적 파일 호스팅 서비스입니다. marimo WASM 내보내기는 Cloudflare Pages 전용 플래그도 지원합니다.
marimo export html-wasm notebook.py -o output_dir --include-cloudflare--include-cloudflare를 추가하면 Cloudflare Pages 배포에 필요한 설정 파일을 함께 생성합니다. Cloudflare Pages에 연결된 GitHub 저장소에 결과물을 푸시하면 자동 배포됩니다.
업데이트 방법
노트북을 수정하면 내보내기를 다시 실행하고 결과물을 저장소에 푸시합니다.
# 노트북 수정 후marimo export html-wasm notebook.py -o docsgit add docs/git commit -m "docs: 노트북 업데이트 반영"git push origin mainGitHub Pages는 푸시 후 수분 이내에 자동으로 최신 결과물로 갱신됩니다.
배포 경로 요약
이 파트에서 다룬 배포 경로 전체를 마지막으로 정리합니다.
| 배포 방법 | 서버 필요 | 상호작용 | 패키지 제약 | 비용 |
|---|---|---|---|---|
marimo run 직접 실행 |
필요 | 있음 | 없음 | 서버 비용 |
| Docker 컨테이너 | 필요 | 있음 | 없음 | 서버 비용 |
| WASM + GitHub Pages | 불필요 | 있음 | Pyodide 지원 패키지만 | 무료 (공개 저장소) |
| 정적 HTML | 불필요 | 없음 | 없음 | 무료 |
상호작용이 필요하고 패키지 제약이 없어야 한다면 Docker 기반 서버 배포를 선택합니다. 패키지 제약 안에서 동작하는 앱이라면 WASM과 GitHub Pages 조합이 서버 비용 없이 배포할 수 있는 좋은 방법입니다. 결과를 정적으로 기록하거나 공유하는 용도라면 정적 HTML 내보내기로 충분합니다.
다음 단계
PART 09에서 배포 경로 전체를 다뤘습니다. PART 10에서는 배포된 앱을 운영하면서 만날 수 있는 실전 함정을 살펴봅니다. 반응형 실행 디버깅, 성능 프로파일링, 보안 주의사항, 테스트 자동화, CI/CD 통합이 차례로 이어집니다.
정리
marimo export html은 실행 결과를 정적 HTML로 내보냅니다. 위젯 조작이 불가능하며 보고서 공유에 적합합니다.marimo export html-wasm은 상호작용이 가능한 WASM HTML을 내보냅니다. Pyodide 지원 패키지 안에서 동작하는 앱에 적합합니다.- WASM 결과물을 GitHub Pages에 게시하면 별도 서버 없이 공개 URL로 앱을 배포할 수 있습니다.
docs디렉토리에 내보내고 Pages 설정에서 소스를 지정하면 됩니다. --include-cloudflare플래그는 Cloudflare Pages 배포에 필요한 설정 파일을 함께 생성합니다.- 배포 방법 선택은 상호작용 필요 여부, 패키지 제약, 서버 비용 세 가지 기준으로 결정합니다.