Skip to main content

​
Overview

There are two recommended ways to set up a local environment for working on the Web Stories plugin:
  1. Docker Container (recommended) - Command-line setup using the provided Docker configuration, also used for E2E tests
  2. Local by Flywheel - Easy-to-use GUI application
Local by Flywheel makes it easy to switch PHP & WordPress versions and supports HTTPS. HTTPS is required for some features like video optimization to work properly.

​
Docker Container Setup

The quickest way to get up and running is to use the provided Docker setup.
Windows users: It is highly recommended to use Windows Subsystem for Linux (WSL) 2 before trying to set up Docker on Windows. Setups without WSL have not been tested and might not work.

​
Starting the Environment

1

Start Docker

The following command will automatically verify whether Docker is configured properly and start the local WordPress instance:
npm run env:start
This script:
  • Checks Docker installation and configuration
  • Launches containers via bin/local-env/launch-containers.sh
  • Installs WordPress via bin/local-env/install-wordpress.sh
  • Activates the Web Stories plugin
2

Access WordPress

The WordPress installation will be available at:
  • Site URL: http://localhost:8899
  • Admin URL: http://localhost:8899/wp-admin
  • Username: admin
  • Password: password
3

Build the Plugin

Run the development build to compile assets:
npm run dev
Or use React Fast Refresh for automatic browser updates:
npm run serve

​
Managing the Environment

npm run env:stop
Stop the environment when you’re done working: 
npm run env:stop
Restart later by running: 
npm run env:start
Reset the database if you need a fresh WordPress installation: 
npm run env:reset-site

​
Specifying PHP Version

You can run the local environment with different PHP versions: 
PHP_VERSION=8.0 npm run env:start

PHP_VERSION=7.4 npm run env:start

​
Docker Configuration

The Docker setup is configured in bin/local-env/:
  • docker-compose.yml - Docker services configuration
  • start.sh - Main startup script
  • stop.sh - Shutdown script
  • launch-containers.sh - Container launch logic
  • install-wordpress.sh - WordPress installation script
  • includes.sh - Shared utility functions
  • uploads.ini - PHP upload configuration
See bin/local-env/docker-compose.yml for the complete Docker configuration.

​
Custom Environment Setup

If you prefer using tools like Local by Flywheel, you can clone this repository directly into your wp-content/plugins directory: 
cd /path/to/your/local/site/wp-content/plugins
git clone [email protected]:googleforcreators/web-stories-wp.git web-stories
Symlinks work well if you prefer having your Git projects in a different location or want to use the plugin on multiple environments: 
ln -s /path/to/web-stories-wp /path/to/wp-content/plugins/web-stories
When using a custom environment, make sure to run composer install and npm install in the plugin directory, then build the assets with npm run build:js or npm run dev.

​
Local by Flywheel Setup

1

Install Local

Download and install Local by Flywheel
2

Create a New Site

  • Open Local and create a new WordPress site
  • Choose your preferred PHP version (7.4+)
  • Select WordPress version (latest recommended)
  • Enable HTTPS for full feature support
3

Clone the Repository

Navigate to the site’s plugins directory and clone:
cd ~/Local Sites/your-site/app/public/wp-content/plugins
git clone [email protected]:googleforcreators/web-stories-wp.git web-stories
4

Install Dependencies and Build

cd web-stories
composer install
npm install
npm run dev
5

Activate the Plugin

Go to the WordPress admin and activate the Web Stories plugin

​
Troubleshooting

​
Docker Issues

Port conflicts: If port 8899 is already in use, you can modify the port in bin/local-env/docker-compose.yml. Permission issues: Ensure Docker has permission to access your project directory. Composer not in PATH: 
# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.composer/vendor/bin:$PATH"

​
WSL-Specific Issues

Missing make command: 
sudo apt-get install build-essential
Docker not starting: Ensure WSL 2 is properly configured and Docker Desktop is set to use the WSL 2 backend.

​
Next Steps

Architecture

Learn about the project structure

Testing

Run tests in your local environment

Contributing

Start making contributions

Build docs developers (and LLMs) love

Get started for freeTalk to us