From a856d54bba46424571e40227997eb576c9351396 Mon Sep 17 00:00:00 2001 From: John Leshan Date: Sat, 17 Oct 2026 13:07:04 +0300 Subject: [PATCH 1/3] docs: add cloud setup path via GitHub Codespaces --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index c49c53ece..75f796724 100644 --- a/README.md +++ b/README.md @@ -219,6 +219,38 @@ the container. +### Path 4 — GitHub Codespaces (cloud, no local GPU) + +Runs the same dev server in a cloud workspace, so integrated graphics and a +local GPU never come into it. GitHub Free includes 120 core-hours a month with +no card on file — about 60 hours on the default 2-core machine. Org and +Enterprise plans include no free quota; current terms and quotas apply. + +1. Fork this repository, then open **your fork** on GitHub. +2. Click the green **Code** button, the **Codespaces** tab, then **Create codespace on main**. +3. In the codespace terminal: + ```bash + nvm install 24 && nvm use 24 + npm ci + npm run doctor + GEV_ALLOWED_HOSTS="$CODESPACE_NAME-4173.$GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN" npm run dev + ``` +4. Open the **Ports** tab, find `4173`, and click the globe icon to open it in + the browser. The port is private by default, so the URL asks for your GitHub + login. + +`GEV_ALLOWED_HOSTS` there is required, not optional. The dev server answers only +the hostnames it trusts, and a forwarded port arrives on +`$CODESPACE_NAME-4173.$GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN`. Without it the +page is `Blocked request. This host is not allowed.` Leading-dot wildcards are +ignored on purpose, so pass that exact name. + +⚠️ **A codespace is reachable from the internet.** Treat it as the +wider-publish case in [Sharing an instance](#-sharing-an-instance): leave +Provider Settings closed to strangers, and put keys in the workspace `.env` by +hand. `.env` is gitignored — never commit it. [SECURITY.md](SECURITY.md) has the +threat model. + ### Then power it up — in the app, not in a file Keys are upgrades, not prerequisites. When you want one, click the **POWER UP** From 295e164fc3dac706ad51a47013e41e4f95441bd8 Mon Sep 17 00:00:00 2001 From: Said Turksever Date: Mon, 19 Oct 2026 14:31:09 +0100 Subject: [PATCH 2/3] docs(readme): say Codespaces moves the server, not the rendering The globe renders in the viewer's own browser, so a codespace does not remove the need for local graphics. Retitle Path 4 accordingly. Co-Authored-By: Claude Opus 5.5 --- README.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 0e1f6ffe7..ce2e97ab9 100644 --- a/README.md +++ b/README.md @@ -219,12 +219,14 @@ the container. -### Path 4 — GitHub Codespaces (cloud, no local GPU) +### Path 4 — GitHub Codespaces (cloud, no local install) -Runs the same dev server in a cloud workspace, so integrated graphics and a -local GPU never come into it. GitHub Free includes 120 core-hours a month with -no card on file — about 60 hours on the default 2-core machine. Org and -Enterprise plans include no free quota; current terms and quotas apply. +Runs the same dev server in a cloud workspace, so Node and the dependencies +never touch your machine. The globe still renders in your own browser, so it +needs the same graphics there as any other path. GitHub Free includes 120 +core-hours a month with no card on file — about 60 hours on the default 2-core +machine. Org and Enterprise plans include no free quota; current terms and +quotas apply. 1. Fork this repository, then open **your fork** on GitHub. 2. Click the green **Code** button, the **Codespaces** tab, then **Create codespace on main**. From 91269cda241f567918c11d0f73ebc7e6c6f043f0 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Mon, 2 Nov 2026 07:02:34 -0800 Subject: [PATCH 3/3] Keep the Codespaces port private, say Provider Settings stays shut there, and credit the path --- README.md | 11 ++++++----- changelog.d/980-codespaces-setup.md | 3 +++ 2 files changed, 9 insertions(+), 5 deletions(-) create mode 100644 changelog.d/980-codespaces-setup.md diff --git a/README.md b/README.md index 1d3c3667c..dcd9ff400 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ Start with the included data sources, then add your own. Each layer is a separat ## ⚡ Quick Start -**Start without an account or API keys.** Both paths open the same app with +**Start without an account or API keys.** Every path opens the same app with Esri satellite imagery and keyless terrain. OSM is the fallback if Esri is unreachable. Flights, military traffic, satellites, earthquakes, public cameras, radio, and launches are available without keys. @@ -253,7 +253,8 @@ quotas apply. ``` 4. Open the **Ports** tab, find `4173`, and click the globe icon to open it in the browser. The port is private by default, so the URL asks for your GitHub - login. + login. Keep it private: a public port lets anyone use the app and the keys + in your `.env`. `GEV_ALLOWED_HOSTS` there is required, not optional. The dev server answers only the hostnames it trusts, and a forwarded port arrives on @@ -262,9 +263,9 @@ page is `Blocked request. This host is not allowed.` Leading-dot wildcards are ignored on purpose, so pass that exact name. ⚠️ **A codespace is reachable from the internet.** Treat it as the -wider-publish case in [Sharing an instance](#-sharing-an-instance): leave -Provider Settings closed to strangers, and put keys in the workspace `.env` by -hand. `.env` is gitignored — never commit it. [SECURITY.md](SECURITY.md) has the +wider-publish case in [Sharing an instance](#-sharing-an-instance). Provider +Settings does not open on the forwarded URL, so put keys in the workspace +`.env` by hand. `.env` is gitignored — never commit it. [SECURITY.md](SECURITY.md) has the threat model. ### Then power it up — in the app, not in a file diff --git a/changelog.d/980-codespaces-setup.md b/changelog.d/980-codespaces-setup.md new file mode 100644 index 000000000..57acd7094 --- /dev/null +++ b/changelog.d/980-codespaces-setup.md @@ -0,0 +1,3 @@ +- Document GitHub Codespaces as a fourth setup path in the README: a cloud + workspace runs the dev server while the globe renders in your own browser + (John Leshan, @johnleshan, #980).