cf deploy: publish playground + explorer to Cloudflare Pages

pthom · pthom · commit 324ee20a8da4 · 2026-04-19T22:56:40.000+02:00
Adds a composed deploy pipeline to imgui-bundle.pages.dev, hosting:
- playground_python/ (pyodide playground)
- min_pyodide_app/ (minimal pyodide template)
- explorer/ (ibex emscripten build)

Local flow via new `cf_*` justfile recipes (cf_stage_all, cf_deploy,
cf_serve_local, cf_clean). Manually triggered CI workflow mirrors the
same flow via cloudflare/wrangler-action. Existing traineq rsync
recipes are kept as fallbacks.

COOP/COEP headers are scoped to /explorer/* via a _headers file to
avoid breaking the playground's CDN fetches.
diff --git a/.github/workflows/cf_pages_deploy.yml b/.github/workflows/cf_pages_deploy.yml
@@ -0,0 +1,65 @@
+name: Cloudflare Pages deploy
+
+on:
+  workflow_dispatch:
+#  pull_request:
+#  release:
+#    types:
+#      - published
+#  push:
+#    branches:
+#      - master
+#      - main
+
+# Refuse concurrent runs
+concurrency:
+  group: cf-pages-deploy
+  cancel-in-progress: false
+
+jobs:
+  build_ibex:
+    name: Build Bundle Explorer Wasm binaries
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: recursive
+
+      # install just
+      - uses: extractions/setup-just@v4
+
+      # install emscripten (and cache it)
+      - name: Setup emsdk
+        uses: emscripten-core/setup-emsdk@v15
+        with:
+          # Make sure to set a version number!
+          version: 5.0.4
+          # This is the name of the cache folder.
+          # The cache folder will be placed in the build directory,
+          #  so make sure it doesn't conflict with anything!
+          actions-cache-folder: 'emsdk-cache'
+
+      - name: Verify emscripten toolchain
+        run: emcc -v
+
+      - name: Setup interactive tmate session
+        uses: mxschmitt/action-tmate@v3
+
+      - name: Build Pyodide wheel
+        run: |
+          just pyodide_setup_local_build
+          just pyodide_build
+
+      - name: Build Bundle Binaries
+        run: just ibex_build
+
+      - name: Stage site
+        run: just cf_stage_all
+
+      - name: Deploy to Cloudflare Pages
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy pyodide_projects/_cf_staging --project-name=imgui-bundle
diff --git a/.gitignore b/.gitignore
@@ -175,6 +175,5 @@ hello_imgui.ini
 _backends
 emsdk/
 .aider*
-
-_mdmath_draft/
+.wrangler/
 
diff --git a/ci_scripts/webserver_multithread_policy.py b/ci_scripts/webserver_multithread_policy.py
@@ -16,10 +16,14 @@
 import argparse
 
 
+COI_PREFIX = ''  # set by main(); empty string = apply site-wide
+
+
 class CORSRequestHandler (SimpleHTTPRequestHandler):
     def end_headers (self):
-        self.send_header('Cross-Origin-Opener-Policy', 'same-origin')
-        self.send_header('Cross-Origin-Embedder-Policy', 'require-corp')
+        if not COI_PREFIX or self.path.startswith(COI_PREFIX):
+            self.send_header('Cross-Origin-Opener-Policy', 'same-origin')
+            self.send_header('Cross-Origin-Embedder-Policy', 'require-corp')
         SimpleHTTPRequestHandler.end_headers(self)
 
     def do_GET(self):
@@ -49,8 +53,11 @@ def do_GET(self):
     parser = argparse.ArgumentParser()
     parser.add_argument('-p', '--port', default=8000, type=int)
     parser.add_argument('-r', '--root', default='', type=str)
+    parser.add_argument('--coi-prefix', default='', type=str,
+                        help='Only set COOP/COEP on URLs under this prefix (e.g. /explorer/). Empty = site-wide.')
     args = parser.parse_args()
     if args.root:
         os.chdir(args.root)
+    globals()['COI_PREFIX'] = args.coi_prefix
     print(f"http://localhost:{args.port}/")
     test(CORSRequestHandler, HTTPServer, port=args.port)
diff --git a/docs/book/_toc.yml b/docs/book/_toc.yml
@@ -54,5 +54,6 @@ parts:
       - file: devel_docs/bindings_debug
       - file: devel_docs/pypi_deploy
       - file: devel_docs/Readme_pyodide_bundle
+      - file: devel_docs/cloudflare_deploy
       - file: devel_docs/build_opencv_immvision
 
diff --git a/docs/book/devel_docs/cloudflare_deploy.md b/docs/book/devel_docs/cloudflare_deploy.md
@@ -0,0 +1,91 @@
+# Cloudflare Pages deploy
+
+The project publishes three static subparts to a single Cloudflare Pages project
+named `imgui-bundle`, reachable at <https://imgui-bundle.pages.dev/>:
+
+| Path                          | Contents                                                          |
+|-------------------------------|-------------------------------------------------------------------|
+| `/playground_python/`         | Pyodide playground (Python examples in the browser)               |
+| `/min_pyodide_app/`           | Minimal Pyodide template (single-file demo)                       |
+| `/explorer/`                  | Dear ImGui Bundle Explorer (Emscripten build with OpenCV)         |
+| `/local_wheels/`              | Shared `imgui_bundle-*.whl`, loaded by the pyodide subparts       |
+
+A tracked landing page at the root (`pyodide_projects/cf_landing.html`) links to
+each subpart. A `_headers` file (`pyodide_projects/cf_headers`) scopes
+`Cross-Origin-Opener-Policy` / `Cross-Origin-Embedder-Policy` to `/explorer/*`
+only; site-wide COI would break the playground (which pulls Pyodide and
+CodeMirror from CDNs that don't set `Cross-Origin-Resource-Policy`).
+
+
+## How the deploy works
+
+Cloudflare Pages replaces the whole site on every upload, so we maintain a
+local composed staging directory (`pyodide_projects/_cf_staging/`, gitignored)
+that holds the union of all subparts. `just cf_stage_all` refreshes every
+subdir; `just cf_deploy` uploads the whole staging tree via `wrangler`.
+
+The trade-off: on every deploy the other subparts must already be present in
+staging. If staging gets wiped (`just cf_clean`), re-run `cf_stage_all` before
+`cf_deploy`.
+
+
+## One-time setup
+
+1. **Install wrangler** (needs Node.js 18+):
+   ```bash
+   npm install -g wrangler
+   ```
+
+2. **Create an API token** at <https://dash.cloudflare.com/profile/api-tokens>
+   using the **Edit Cloudflare Workers** template (it covers Pages too).
+
+3. **Export credentials** in your shell (or your shell rc):
+   ```bash
+   export CLOUDFLARE_API_TOKEN=...
+   export CLOUDFLARE_ACCOUNT_ID=...
+   ```
+
+4. **Verify**: `wrangler whoami` should print the account.
+
+
+## Local workflow
+
+```bash
+# Full refresh of staging, then deploy
+just cf_stage_all
+just cf_deploy
+
+# Test the composed site locally before deploying
+just cf_serve_local        # http://localhost:8765/
+# → COOP/COEP headers are applied only to /explorer/* (mirrors prod)
+
+# Inspect the staging tree (gitignored)
+ls pyodide_projects/_cf_staging/
+
+# Nuke staging (forces a full re-stage next time)
+just cf_clean
+```
+
+The ibex subpart requires `just ibex_build` first (produces
+`build_ibex_ems/bin/`); `cf_stage_all` then copies those binaries into
+`_cf_staging/explorer/`.
+
+
+## CI workflow
+
+`.github/workflows/cf_pages_deploy.yml` mirrors the local flow and is
+triggered manually from the Actions tab (`workflow_dispatch`). It runs:
+
+1. `just pyodide_setup_local_build` + `just pyodide_build` (builds the wheel)
+2. `just ibex_build` (builds Emscripten binaries; slowest step, typically
+   30–60 min because `IMMVISION_FETCH_OPENCV=ON` rebuilds OpenCV for wasm)
+3. `just cf_stage_all`
+4. `cloudflare/wrangler-action@v3` to upload
+
+Required GitHub Actions secrets: `CLOUDFLARE_API_TOKEN`,
+`CLOUDFLARE_ACCOUNT_ID` (same values used locally).
+
+
+## Related
+
+- Local traineq deploy (kept as fallback): `just pyodide_deploy_imgui_bundle_online`, `just ibex_deploy`
diff --git a/docs/book/devel_docs/intro.md b/docs/book/devel_docs/intro.md
@@ -67,4 +67,5 @@ Terms used throughout the developer docs:
 - [Debug Native C++](bindings_debug.md) – debugging C++ code from Python
 - [PyPI Deployment](pypi_deploy.md) – releasing to PyPI
 - [Pyodide Build Guide](Readme_pyodide_bundle.md) – building for Python-in-the-browser
+- [Cloudflare Pages Deploy](cloudflare_deploy.md) – publishing the playground + explorer to imgui-bundle.pages.dev
 - [OpenCV Build Guide](build_opencv_immvision.md) – building with OpenCV / ImmVision
diff --git a/justfile b/justfile
@@ -71,7 +71,7 @@ libs_bindings_all:
 ibex_build:
     mkdir -p build_ibex_ems && \
     cd build_ibex_ems && \
-    source ~/emsdk/emsdk_env.sh && \
+    if [ -f ~/emsdk/emsdk_env.sh ]; then source ~/emsdk/emsdk_env.sh; fi && \
     emcmake cmake .. -DCMAKE_BUILD_TYPE=Release -DIMMVISION_FETCH_OPENCV=ON && \
     make -j
 
@@ -108,7 +108,7 @@ ibex_serve:
 imex_ems_build:
     mkdir -p build_imex_ems && \
     cd build_imex_ems && \
-    source ~/emsdk/emsdk_env.sh && \
+    if [ -f ~/emsdk/emsdk_env.sh ]; then source ~/emsdk/emsdk_env.sh; fi && \
     emcmake cmake .. -DCMAKE_BUILD_TYPE=Release \
                      -DIMGUI_BUNDLE_BUILD_IMGUI_EXPLORER_APP=ON -DIMGUI_BUNDLE_WITH_IMANIM=OFF -DIMGUI_BUNDLE_BUILD_DEMOS=OFF -DIMGUI_BUNDLE_WITH_IMMVISION=OFF && \
     cmake --build . -j 8
@@ -245,6 +245,65 @@ pyodide_deploy_imgui_bundle_online:
     echo "Deployed to https://traineq.org/imgui_bundle_online/"
 
 
+# ==============================================================
+# Cloudflare Pages deploy (to https://imgui-bundle.pages.dev/)
+# ==============================================================
+# See docs/book/devel_docs/cloudflare_deploy.md for the full workflow.
+#
+#   imgui-bundle.pages.dev/                      landing page (links)
+#   imgui-bundle.pages.dev/playground_python/    pyodide playground
+#   imgui-bundle.pages.dev/min_pyodide_app/      minimal pyodide sample
+#   imgui-bundle.pages.dev/local_wheels/         shared wheel (referenced as ../local_wheels/)
+#   imgui-bundle.pages.dev/explorer/             ibex
+#
+# Requires: wrangler (`npm i -g wrangler`) and either
+#   - env vars CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID, or
+#   - `wrangler login` / `wrangler whoami` auth
+_CF_STAGING := "pyodide_projects/_cf_staging"
+_CF_PROJECT := "imgui-bundle"
+
+# populates pyodide_projects/_cf_staging which is what will be uploaded to imgui-bundle.pages.dev/
+[group('cloudflare')]
+cf_stage:
+    # 0. Make dir pyodide_projects/_cf_staging (gitignored)
+    mkdir -p {{_CF_STAGING}}
+    # 1. Copy landing page and CF _headers file
+    # ------------------------------------------------------------
+    cp pyodide_projects/cf_landing.html {{_CF_STAGING}}/index.html
+    cp pyodide_projects/cf_headers {{_CF_STAGING}}/_headers
+    # 2. Copy min_pyodide_app
+    # ------------------------------------------------------------
+    rm -rf {{_CF_STAGING}}/min_pyodide_app
+    cd pyodide_projects/projects/min_bundle_pyodide_app && cp -f demo_heart.html demo_heart.source.txt
+    rsync -a pyodide_projects/projects/min_bundle_pyodide_app/ {{_CF_STAGING}}/min_pyodide_app/
+    # 3. Copy python playground
+    # ------------------------------------------------------------
+    # --copy-unsafe-links resolves the examples/ symlink (points outside the tree)
+    rm -rf {{_CF_STAGING}}/playground_python {{_CF_STAGING}}/local_wheels
+    rsync -a --copy-unsafe-links pyodide_projects/projects/imgui_bundle_playground/ {{_CF_STAGING}}/playground_python/
+    rsync -a pyodide_projects/projects/local_wheels/ {{_CF_STAGING}}/local_wheels/
+    # 4. Copy bundle explorer (ibex)
+    # ------------------------------------------------------------
+    rm -rf {{_CF_STAGING}}/explorer
+    rsync -a --exclude='*.gz' build_ibex_ems/bin/ {{_CF_STAGING}}/explorer/
+    cp build_ibex_ems/bin/demo_imgui_bundle.html {{_CF_STAGING}}/explorer/index.html
+
+# Upload the current staging dir to Cloudflare Pages (the whole site snapshot)
+[group('cloudflare')]
+cf_deploy:
+    wrangler pages deploy {{_CF_STAGING}} --project-name={{_CF_PROJECT}} --commit-dirty=true
+    echo "Deployed to https://imgui-bundle.pages.dev/"
+
+# Wipe staging
+[group('cloudflare')]
+cf_clean:
+    rm -rf {{_CF_STAGING}}
+
+# Serves locally the current staging dir (add coi headers for the explorer)
+[group('cloudflare')]
+cf_serve_local:
+    cd {{_CF_STAGING}} && python ../../ci_scripts/webserver_multithread_policy.py -p 8765 --coi-prefix=/explorer/
+
 # ==============================================================
 # Tests
 # ==============================================================
diff --git a/pyodide_projects/.gitignore b/pyodide_projects/.gitignore
@@ -0,0 +1 @@
+_cf_staging/
diff --git a/pyodide_projects/cf_headers b/pyodide_projects/cf_headers
@@ -0,0 +1,9 @@
+# Cloudflare Pages _headers file (copied to _cf_staging/_headers at stage time).
+# Syntax: https://developers.cloudflare.com/pages/configuration/headers/
+#
+# Scope COOP/COEP to /explorer/* only. Site-wide would break the playground,
+# which pulls Pyodide from a CDN that doesn't set CORP headers.
+
+/explorer/*
+  Cross-Origin-Opener-Policy: same-origin
+  Cross-Origin-Embedder-Policy: require-corp
diff --git a/pyodide_projects/cf_landing.html b/pyodide_projects/cf_landing.html
@@ -0,0 +1,56 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Dear ImGui Bundle — Online</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      max-width: 640px;
+      margin: 4em auto;
+      padding: 0 1em;
+      line-height: 1.5;
+      color: #222;
+    }
+    h1 { margin-bottom: 0.2em; }
+    .tag { color: #888; font-size: 0.9em; margin-bottom: 2em; }
+    ul { list-style: none; padding: 0; }
+    li { margin: 0.8em 0; }
+    a { color: #0366d6; text-decoration: none; font-weight: 500; }
+    a:hover { text-decoration: underline; }
+    .desc { color: #555; font-size: 0.9em; }
+    footer { margin-top: 4em; color: #888; font-size: 0.85em; }
+  </style>
+</head>
+<body>
+<h1>Dear ImGui Bundle</h1>
+<div class="tag">Online demos and tools.</div>
+
+<ul>
+  <li>
+    <a href="playground_python/">Python Playground (Pyodide)</a><br>
+    <span class="desc">Edit and run Dear ImGui Bundle Python examples in your browser.</span>
+  </li>
+  <li>
+    <a href="min_pyodide_app/demo_heart.html">Minimal Pyodide Template</a><br>
+    <span class="desc">Minimal Template showing Dear ImGui Bundle app running in the browser.</span>
+  </li>
+  <li>
+    <a href="min_pyodide_app/demo_heart.source.txt">Minimal Pyodide Template - Source</a><br>
+    <span class="desc">Minimal Template Source.</span>
+  </li>
+
+  <!--    <li>-->
+  <!--      <a href="explorer/">ImGui Bundle Explorer</a><br>-->
+  <!--      <span class="desc">Interactive explorer for Dear ImGui Bundle C++ demos (Emscripten).</span>-->
+  <!--    </li>-->
+
+</ul>
+
+<footer>
+  <a href="https://github.com/pthom/imgui_bundle">GitHub</a> ·
+  <a href="https://pthom.github.io/imgui_bundle/">Documentation</a>
+</footer>
+</body>
+</html>
