xwp / vip-go-site
VIP Go site environment
Installs: 81
Dependents: 0
Suggesters: 0
Security: 0
Stars: 33
Watchers: 32
Forks: 9
Open Issues: 23
Type:project
Requires
- php: >=8.2
- automattic/wpcom-legacy-redirector: dev-develop
- composer/installers: ^1|^2.2
- cweagans/composer-patches: ^1.7
- wpackagist-plugin/action-scheduler: ^3.9
- wpackagist-plugin/safe-svg: ^2.3
- wpackagist-plugin/wp-crontrol: ^1.19
- wpackagist-theme/twentytwentyfive: ^1.3
- xwp/example-theme: @dev
Requires (Dev)
- automattic/vip-go-mu-plugins: dev-master
- automattic/vipwpcs: ^3.0
- dealerdirect/phpcodesniffer-composer-installer: ^1.1
- php-stubs/wordpress-stubs: ^6.8
- php-stubs/wp-cli-stubs: ^2.12
- phpcompatibility/php-compatibility: ^9.3
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^9.6
- roots/wordpress: ^6.8
- szepeviktor/phpstan-wordpress: ^1.3
- wp-cli/php-cli-tools: ^0.11
- wp-phpunit/wp-phpunit: ^6.8
- xwp/wait-for: ^0.0.2
- yoast/phpunit-polyfills: ^2.0
- dev-master
- dev-feature/dk-improvements
- dev-renovate/automattic-vip-3.x
- dev-renovate/wordpress-monorepo
- dev-renovate/jwilder-nginx-proxy-1.x
- dev-renovate/elasticsearch-7.x
- dev-renovate/yoast-phpunit-polyfills-2.x
- dev-renovate/wp-phpunit-wp-phpunit-6.x
- dev-renovate/npm-run-all2-5.x
- dev-renovate/automattic-vipwpcs-3.x
- dev-renovate/npm-run-all-replacement
- dev-renovate/phpunit-phpunit-9.x
- dev-dependabot/npm_and_yarn/wordpress-ad7187a3a8
- dev-dependabot/github_actions/actions/checkout-5
- dev-dependabot/github_actions/actions/setup-node-5
- dev-add/simplify-setup
- dev-feature/lint-yaml
- dev-feature/js-deploy
This package is auto-updated.
Last update: 2025-09-26 11:10:13 UTC
README
Site setup, development environment and deploy tooling for WordPress VIP:
- Uses Composer for adding project dependencies, including plugins and themes.
- Uses Composer autoloader for using any of the popular PHP packages anywhere in the codebase.
- Includes a local development environment based on Docker with support for PHP Xdebug and a mail catcher.
- Includes automated build and deploy pipelines to WordPress VIP Go using GitHub Actions.
Links & Resources
Requirements
- PHP 8.2
- Composer
- Node.js version 20
- Docker with Docker Compose
- rsync for deployments
Install Dependencies
We suggest using Homebrew on macOS or Chocolatey for Windows to install the project dependencies.
brew install git php@8.2 composer node@20 mkcert nss
brew install --cask docker
Once NVM is installed, you can install the required Node.js version from the .nvmrc
file:
nvm install
nvm use
WordPress Compatibility
This theme template is aligned with WordPress 6.8.x package versions.
To update packages to match a different WordPress version:
npx wp-scripts packages-update --dist-tag=wp-[version] --save
Code Editor and Git Client
This repository includes a list of suggested extensions for the Visual Studio Code editor and Xdebug support in the .vscode
directory.
A user-friendly Git client such as GitHub Desktop or Tower enables smaller commits and simplifies merge conflict resolution.
Overview
- Project plugins and themes can be added as Composer dependencies or manually to this repository under
plugins/your-plugin
andthemes/your-theme
. - Composer dependencies are placed under
plugins/vendor
since it has to be in the same location relative to the project root (which is not the case forvip-config
, which is mapped to the WP root directory on the server). - Composer autoloader
plugins/vendor/autoload.php
is included invip-config/vip-config.php
.
Initial Setup
Important: This section can be deleted once you've completed the initial setup from the VIP Go Site template.
The site project generated from this template is designed to be hosted under the WP VIP GitHub organization which is why it uses GitHub Actions for deployments - GitHub Action based workflow.
VIP Platform Configuration
The following configuration must be requested from VIP Go to use this site repository:
- Deployments from
*-built
branches such asmain-built
anddevelop-built
. - Staging environment tracking the
develop-built
branch.
VIP Repository Setup
-
Ensure that VIP has configured the site to deploy from the
*-built
branches. -
Create a fresh local Git repository from this reference repository:
composer create-project xwp/vip-site-template --stability dev
-
Add your theme and plugins as Composer dependencies:
composer require your/theme your/plugin another/plugin
or by manually copying them to
themes
orplugins
. Remember to start tracking those directories by excluding them inthemes/.gitignore
andplugins/.gitignore
. -
Adjust strings and URLs in all files match your project. Search and replace the following strings:
xwp/vip-site-template
,xwp-vip-site-template
,wpcomvip/devgo-vip
,XWP\VIP_Site_Template
,network.local.wpenv.net
,main.local.wpenv.net
,XWP_VIP_Site_Template
,xwp/example-theme
,themes/example-theme
example-theme
. -
If hosting this source repository under the VIP GitHub organization, add the VIP Go upstream repository as another remote to this repository locally and force-push the current
main
to that upstream repository to override themain
branch with this. Do the same for thedevelop
branch.For hosting this source repository under any other GitHub organization, simply push it to that repository.
-
Generate a fresh SSH key pair and add the private part as a
DEPLOY_SSH_KEY
GitHub Actions secret, and the public part as the Deploy key to the VIP GitHub repository.ssh-keygen -f deploy-key -t rsa -b 4096 -C "technology+project-name@xwp.co"
This provides GitHub Actions with access to the VIP repository for deployments.
-
Remove references to either GitHub actions from this README depending on which deploy strategy was selected.
-
Remove these initial setup instructions from the README after the initial project setup.
Setup ðŸ›
-
Clone this repository:
git clone git@github.com:xwp/vip-site-template.git devgo-vip
-
Move into the project directory:
cd devgo-vip
-
Install the project dependencies:
npm install
-
Install ssl certificate to add the certificate authority of the development environment
local/data/mkcert/rootCA.pem
to the trusted list on your computer. Alternatively, configure it manually.npm run install-cert
-
Start the development environment using Docker:
npm run start
and
npm run stop
to stop the virtual environment at any time. Runnpm run start-debug
to start the environment in debug mode where all output from containers is displayed. Runnpm run stop-all
to stop all active Docker containers in case you're running into port conflicts. -
Install the local WordPress environment:
npm run setup
with the configuration from
wp-cli.yml
. -
Visit network.local.wpenv.net for the network admin or main.local.wpenv.net for the main site. WordPress username
devgo
and passworddevgo
. -
Visit mail.local.wpenv.net to view all emails sent by WordPress.
The local development environment uses a self-signed SSL certificate for HTTPS so the "Your connection is not private" error can be ignored to visit the site.
Resolving Port Conflicts
Docker engine shares the networking interface with the host computer, so all the ports used by the containers must be free and unused by any other services such as a DNS resolver on port 53, MySQL service on port 3306 or another web server running on port 80.
Use the included npm run stop-all
command to stop all containers running Docker containers on the host machine. Alternatively, you can adjust the port mappings in docker-compose.yml
to expose different ports on the host machine.
Contribute
-
Setup the local environment environment as described in the "Setup" section above.
-
Create a Git branch such as
feature/name
orfix/vertical-scroll
when you start working on a feature or a bug fix. You can use thedevelop
branch for your own testing and development. -
Open a pull request from your feature branch to the
main
branch for code review. -
Review any feedback from the automated checks (linting, testing).
-
Once approved, squash and merge the PR into
main
. This automatically deploys to the test environment.
Plugins and Themes
Add new themes and plugins as Composer dependencies:
composer require your/theme your/plugin another/plugin
or manually copy them to themes
, plugins
or client-mu-plugins
directories. Remember to start tracking the directories copied manually by excluding them from being ignored in themes/.gitignore
and plugins/.gitignore
.
Use client-mu-plugins/plugin-loader.php
to force-enable certain plugins.
To update plugins and themes added as Composer dependencies, use composer install package/name
or composer install --dev package/name
where package/name
is the name of the plugin or theme package. Be sure to commit the updated composer.json
with composer.lock
to the GitHub repository.
For manually installed plugins and themes replace the directory with the updated set of files and commit them to the GitHub repository.
Local Development Environment
We use Docker containers to replicate the VIP Go production environment with all VIP dependencies added as Composer packages and mapped to specific directories inside the containers as defined in docker-compose.yml
.
Requests to port 80 of the container host are captured by an Nginx proxy container that routes all requests to the necessary service container based on the HTTP hostname.
Importing and Exporting Data
Use VIP dashboard or VIP-CLI to download the database data from the production environment.
-
Run
npm run vip -- export sql --output=local/public/wp/vip-export.sql
to download the latest available backup to your local computer. -
Run
npm run cli -- wp db export
to export and backup the database of your local development environment, which will place a file likewordpress-2020-03-04-448b132.sql
in thelocal/public/wp
directory. -
Run
npm run cli -- wp db import vip-export.sql
to importlocal/public/wp/vip-export.sql
into your local development environment. -
Run
npm run cli -- bash -c "pv import.sql | wp db query"
to import a large database filelocal/public/wp/vip-export.sql
while monitoring the progress withpv
which is bundled with the WordPress container. Thebash -c
prefix allows us to run multiple commands inside the container without affecting the mainnpm run cli
command.
Scripts 🧰
We use npm
as the canonical task runner for things like linting files and creating release bundles. Composer scripts (defined in composer.json
) are used only for PHP related tasks and they have a wrapper npm script in package.json
for consistency with the rest of the registered tasks.
-
npm run start
andnpm run stop
to start and stop the local development environment. Runnpm run start-debug
to start the environment in debug mode, where all output from containers is displayed. Runnpm run stop-all
to stop all active Docker containers in case you're running into port conflicts. Runnpm run stop -- --volumes
to stop the project containers and delete the database data volume. -
npm run lint
to check source code against the defined coding standards. -
npm run cli -- wp help
wherewp help
is any command to run inside the WordPress docker container. For example, runnpm run cli -- wp plugin list
to list all of the available plugins ornpm run cli -- composer update
to update the Composer dependencies using the PHP binary in the container instead of your host machine. Runnpm run cli -- wp user create devgo local@devgo.vip --role=administrator --user_pass=devgo
to create a new administrator user withdevgo
as username and password. -
npm run vip
to run VIP CLI commands on staging and production environments. -
npm run install-cert
to mark the self-signed SSL certificate authority (underlocal/certs/rootCA.pem
) for the local development environment as trusted. Make suremkcert
is installed on your computer. This command is required to avoid the "Your connection is not private" error when visiting the site. Stop the local environment before running this command, restart the browser/tab after installing the certificate, and start the environment again.
Release Process & Deployments 🚀
This project follows a structured release process with automated deployments managed by GitHub Actions workflows.
Branch Strategy
Branch | Purpose | Environment | Auto-Deploy |
---|---|---|---|
develop |
Development work | Dev | ✅ |
main |
Staging/testing | Test | ✅ |
release |
UAT testing | Pre-prod | ✅ |
production |
Live site | Production | ✅ |
Release Workflow
- Development: Developers can use
develop
for testing, but create PRs tomain
for code review - Testing: Approved features merged into
main
→ Auto-deploys to test environment - Release Creation: EM/TL creates
release
branch frommain
for UAT → Auto-deploys to pre-prod - Production: After UAT approval,
release
is merged →production
→ Auto-deploys to production
Automated Workflows
Our deployment process uses several automated GitHub Actions workflows:
- Test & Deploy: Runs on all PR/push events - handles linting, testing, and environment-specific deployments
- Note: Tests are skipped for production deployments since code has already been tested in pre-production
- Create Release Branch: Manual workflow for EM/TL to create release branches from main
- Create Production PR: Manual workflow to create production release PRs with comprehensive checklists
- Release Cleanup: Automatic cleanup after production deployments
- Docker Images: Builds and publishes Docker images when needed
📋 Detailed workflow documentation: GitHub Actions Workflows
Environment Configuration
The workflows require specific GitHub secrets and variables to be configured in your repository settings.
📋 Complete configuration details: Workflow Configuration
Technical Details
The deployment process:
- Runs
local/scripts/deploy.sh
which creates a clean build environment - Checks code against VIP coding standards
- Builds release artifacts and filters files using
.distinclude
- Commits changes to the matching VIP branch for server import
NewRelic Integration
Automatic deployment markers are sent to NewRelic (when NEW_RELIC_API_KEY
is configured):
npm run newrelic-mark-deploy -- --search "*-production" --api_key "$NEW_RELIC_API_KEY" --commit "$COMMIT_SHA" --user "$DEPLOY_USER" --description "$COMMIT_MESSAGE"
The --search
parameter finds NewRelic apps using the pattern *-{environment}
where environment matches the VIP environment name.