From 88ecd8fa81c37a364e7837649c6972d275f69635 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= Date: Wed, 4 Nov 2026 22:44:48 +0100 Subject: [PATCH 1/2] [Docs] Build the self-hosted Playground website from source --- .../18-host-your-own-playground.md | 56 ++++++++++--------- 1 file changed, 29 insertions(+), 27 deletions(-) diff --git a/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md b/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md index 768b31f1b5c..281a185e64d 100644 --- a/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md +++ b/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md @@ -63,33 +63,23 @@ const client = await startPlaygroundWeb({ ## Static assets -There are several ways to get the static assets necessary to host the Playground. - -In order of convenience and ease: - -- Download pre-built package -- Fork the repository and build with GitHub Action -- Build locally - -### Download pre-built package - -To host the Playground as is, without making changes, you can download the built artifact from [the latest successful GitHub Action](https://github.com/WordPress/wordpress-playground/actions/workflows/deploy-website.yml?query=is%3Asuccess). - -- Click on **Deploy Playground website**. -- In the section **Artifacts** at the bottom of the page, click `playground-website`. -- It's a zip package with the same files deployed to the public site. - -### Fork the repository and build with GitHub Action - -To customize the Playground, you can [fork the Git repository](https://github.com/WordPress/wordpress-playground/fork). - -Build it from the fork's GitHub page by going to: **Actions -> Deploy Playground website -> Run workflow**. +Build the browser website from source to host it on your own domain. This does +not require a GitHub Actions artifact. The `@wp-playground/client` npm package +connects your app to an already hosted browser runtime. The +`@wp-playground/cli` npm package runs WordPress locally with Node.js. Neither +installs the browser website and its Dock. + +The [Deploy Playground website workflow](https://github.com/WordPress/wordpress-playground/actions/workflows/deploy-website.yml) +produces a temporary artifact for the public deployment. It expires, and the +build is configured to render WordPress on `wpsandbox.wordpress.net`. Use the +source build below for another domain, even if the artifact is still available. +Running the deploy workflow in a fork without the deployment secrets skips +the build, too. ### Build locally -The most flexible and customizable method is to build the site locally. - -Create a shallow clone of the Playground repository, or your own fork. +Create a shallow clone of the Playground repository or your own fork. To pin +the source to a specific version, replace `trunk` with a release tag. ```sh git clone -b trunk --single-branch --depth 1 --recurse-submodules https://github.com/WordPress/wordpress-playground.git @@ -101,20 +91,32 @@ Enter the `wordpress-playground` directory. cd wordpress-playground ``` -Install dependencies, and build the website. +Use the Node.js version in `.nvmrc`, install the locked dependencies, and +build the website: ```sh -npm install +nvm use +npm ci npm run build:website ``` +Leave `PLAYGROUND_APP_ORIGIN` and `VITE_WORDPRESS_SITE_URL` unset to serve +the Playground app and its WordPress pages from the same origin. For a public +instance that runs untrusted plugins or Blueprints, use a separate WordPress +origin instead. See the [split-origin deployment guide](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/website-deployment/wordpress-frame/README.md). + This command internally runs the `nx` task `build:wasm-wordpress-net`. It copies the built assets from packages `remote` and `website` into a new folder at the following path: ``` dist/packages/playground/wasm-wordpress-net ``` -The entire service of the Playground consists of the content of this folder. +Serve the contents of this folder as your site root. + +This builds the files you serve. It does not make every Playground feature +independent of external services. For example, production builds use the +project's CORS proxy for requests that the browser cannot make directly, +unless you set `CORS_PROXY_URL` at build time. ## Summary of included files From fb7b9ce23a01ebf9c0c89113e9b6f4fc5b063555 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Adam=20Zieli=C5=84ski?= Date: Thu, 5 Nov 2026 02:22:38 +0100 Subject: [PATCH 2/2] [Docs] Explain source pinning and split-origin limits for self-hosts --- .../23-architecture/18-host-your-own-playground.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md b/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md index 281a185e64d..0f737ca6c1c 100644 --- a/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md +++ b/packages/docs/site/docs/developers/23-architecture/18-host-your-own-playground.md @@ -79,7 +79,10 @@ the build, too. ### Build locally Create a shallow clone of the Playground repository or your own fork. To pin -the source to a specific version, replace `trunk` with a release tag. +the Playground source to a specific version, replace `trunk` with a release +tag. The tag does not make the build reproducible: the build downloads +`wp-cli.phar` from the `wp-cli/builds` repository's `gh-pages` branch, which +can change between builds. ```sh git clone -b trunk --single-branch --depth 1 --recurse-submodules https://github.com/WordPress/wordpress-playground.git @@ -103,7 +106,8 @@ npm run build:website Leave `PLAYGROUND_APP_ORIGIN` and `VITE_WORDPRESS_SITE_URL` unset to serve the Playground app and its WordPress pages from the same origin. For a public instance that runs untrusted plugins or Blueprints, use a separate WordPress -origin instead. See the [split-origin deployment guide](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/website-deployment/wordpress-frame/README.md). +origin to reduce exposure. This does not fully protect saved files or native +directory handles. See the [split-origin deployment guide](https://github.com/WordPress/wordpress-playground/blob/trunk/packages/playground/website-deployment/wordpress-frame/README.md). This command internally runs the `nx` task `build:wasm-wordpress-net`. It copies the built assets from packages `remote` and `website` into a new folder at the following path: