Host your own Playground
You can host the Playground on your own domain instead of playground.wordpress.net
.
This is useful for having full control over its content and behavior, as well as removing dependency on a third-party server. It can provide a more customized user experience, for example: a playground with preinstalled plugins and themes, default site settings, or demo content.
Usage
A self-hosted Playground can be embedded as an iframe.
<iframe src="https://my-playground.com"></iframe>
Or dynamically loaded by passing the remote URL to the Playground Client.
import { startPlaygroundWeb } from '@wp-playground/client';
const client = await startPlaygroundWeb({
iframe: document.getElementById('wp'),
remoteUrl: `https://my-playground.com/remote.html`,
});
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.
- Click on Deploy to playground.wordpress.net.
- 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.
Build it from the fork's GitHub page by going to: Actions -> Deploy to playground.wordpress.net -> Run workflow.
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.
git clone -b trunk --single-branch --depth 1 git@github.com:WordPress/wordpress-playground.git
Enter the wordpress-playground
directory.
cd wordpress-playground
Install dependencies, and build the website.
npm install
npm run build:website
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.
Summary of included files
The static assets include:
- Data and WASM files for all available PHP and WordPress versions
remote.html
- the core of Playgroundindex.html
- the shell, or browser chrome- Web Worker script
You can deploy the content of the folder to your server using SSH, such as scp
or rsync
.
It is a static site, except for these dynamic aspects.
- Apache server directive
.htaccess
file from the packageremote
For these to work, you need a server environment with Apache and PHP installed.
NGINX configuration
As an alternative to Apache, here is an example of using NGINX to serve the Playground.
The example may be outdated. Please check the source file for the latest version.
The combined Apache .htaccess
file looks like this.
AddType application/wasm .wasm
AddType application/octet-stream .data
An equivalent in NGINX.
location ~* .wasm$ {
types {
application/wasm wasm;
}
}
location ~* .data$ {
types {
application/octet-stream data;
}
}
location /scope:.* {
rewrite ^scope:.*?/(.*)$ $1 last;
}
You may need to adjust the above according to server specifics, particularly how to invoke PHP for the path /plugin-proxy
.
Customize bundled data
The file wp.zip
is a bundle of all the files for the virtual file system in Playground. There's a data file for each available WordPress version.
The package at packages/playground/wordpress
is responsible for building these data files.
Edit the build script in Dockerfile
to create a custom bundle that includes preinstalled plugins or content.
Install plugins
Here's an example of installing plugins for the data bundle.
Before the section titled Strip whitespaces from PHP files
.
# === Preinstall plugins ===
RUN cd wordpress/wp-content/mu-plugins && \
# Install plugins
for plugin_name in example-plugin-1 example-plugin-2; do \
curl -L https://downloads.wordpress.org/plugin/{$plugin_name}.latest-stable.zip -o {$plugin_name}.zip && \
unzip $plugin_file && \
rm $plugin_file && \
# Create entry file in mu-plugins root
echo "<?php require_once __DIR__.'/$plugin_name/$plugin_name.php';" > $plugin_name.php; \
done;
You can download plugins from URLs other than the WordPress plugin directory, or use Git to pull them from elsewhere.
It's also possible to copy from a local folder. For example, before RUN
:
COPY ./build-assets/*.zip /root/
Then put the plugin zip files in build-assets
. In this case, you may want to add their paths to .gitignore
.
Import content
Here's an example of importing content.
# === Demo content ===
COPY ./build-assets/content.xml /root/
RUN cd wordpress ; \
echo "Importing content.."; \
../wp-cli.phar --allow-root import /root/content.xml --authors=create
This assumes that you have put a WXR export file named content.xml
in the folder build-assets
. You can add its path to .gitignore
.