{"id":19045500,"url":"https://github.com/yoast/plugin-development-docker","last_synced_at":"2025-10-30T13:02:59.965Z","repository":{"id":38185789,"uuid":"228364101","full_name":"Yoast/plugin-development-docker","owner":"Yoast","description":"A docker configuration for WordPress plugin development","archived":false,"fork":false,"pushed_at":"2024-06-19T13:39:49.000Z","size":324,"stargazers_count":44,"open_issues_count":10,"forks_count":14,"subscribers_count":17,"default_branch":"main","last_synced_at":"2024-12-11T10:37:26.533Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yoast.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-16T10:42:54.000Z","updated_at":"2024-09-25T14:16:56.000Z","dependencies_parsed_at":"2024-06-19T23:26:13.080Z","dependency_job_id":"a79af9b4-08ca-4911-aadb-a8559b36d3c1","html_url":"https://github.com/Yoast/plugin-development-docker","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yoast%2Fplugin-development-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yoast%2Fplugin-development-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yoast%2Fplugin-development-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yoast%2Fplugin-development-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yoast","download_url":"https://codeload.github.com/Yoast/plugin-development-docker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230431100,"owners_count":18224655,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T22:50:23.896Z","updated_at":"2025-10-30T13:02:59.924Z","avatar_url":"https://github.com/Yoast.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WordPress Plugin Development Docker\n\nThis is a fairly simple docker container to facilitate development of WordPress plugins.\n\n## Prerequisites\n\nMac users:\n\n\u003e **Warning**\n\u003e \n\u003e Do not clone to your documents folder as this will cause permission issues.\n\n- [OrbStack](https://yoast.atlassian.net/wiki/spaces/OPS/pages/3243376643/Container+managers) includes everything you need.\n\nWindows WSL2:\nRunning this setup from WSL is the preferd way. \n\n- [Rancher Desktop](https://rancherdesktop.io/) see the [Rancher-win.md](./Rancher-win.md) guide on how to switch.\n- [GitExtensions](https://github.com/gitextensions/gitextensions/releases/) includes some unix tools we need.\n- optional [GSudo](https://github.com/gerardog/gsudo) allows shell scripts to use sudo command on windows\n\nWindows install:\n\n- Friendly dns names (e.g. basic.wordpress.test) will not work out of the box\n  possible fix: make the `c:\\windows\\system32\\drivers\\etc\\hosts` write and change for users, before running ./setup.sh script from WSL after running the .setup.sh this can be removed again\n- Ssl trust will not work out of the box add the config/certs/wordpress.text.crt to the trusted list in windows it self(NOT WSL)\n  - First copy the cert to the Windows file system. `cp config/certs/wordpress.test.crt /mnt/c/Users/WindowsUserName/Desktop`\n  - Then add the ssl cert to the Windows certificate store. Start a PowerShell prompt and execute `Import-Certificate -FilePath \".\\Desktop\\wordpress.test.crt\" -CertStoreLocation Cert:\\CurrentUser\\Root`\n\n\n## Setting up the local system\n\n### 1. run `./setup.sh`\n\nThis will configure your host-file and create the necessary config files first.\nYou will likely need to enter your sudo password as this will add basic.wordpress.test etc to your hosts file. (see note above for windows)\n\n### 2. run `./start.sh`\n\nThis will create and start your containers. You can visit your environment by visiting `https://basic.wordpress.test`. Note that starting other containers, like woocommerce or multisite, will have different domains associated.\n\n### Resetting everything\n\nYou can always run `./clean.sh` to delete all persistent data of your WordPresss environment and start again from scratch. If you run `./clean.sh --all` you will also remove configuration files.\n\n## Maintenance and CLI commands\n\n### Running alternate or multiple containers\n\nBy default `./start.sh` will start the basic wordpress container. Alternatively you can call `./start.sh $CONTAINER_NAMES` to start other containers.\n\nThe following are available:\n\n- **basic-wordpress**: The basic image that's started by default. Can be accessed via basic.wordpress.test.\n- **standalone-wordpress**: The basic image without anything installed. Has a separate plugins folder named `sa-plugins` in order to not interfere with other containers. Useful for testing a second version of a plugin.\n- **woocommerce-wordpress**: A WooCommerce installation. Can be accessed via woocommerce.wordpress.test.\n- **multisite-wordpress**: A multisite installation using subdirectories. Can be accessed via multisite.wordpress.test.\n- **multisitedomain-wordpress**: A multisite installation using subdomains. Can be accessed via multisite.wordpress.test.\n- **nightly-wordpress**: A nightly installation using subdomains. Can be accessed via nightly.wordpress.test.\n\nFor example, calling `./start.sh woocommerce-wordpress` will start only the WooCommerce container. Calling `./start.sh basic-wordpress multisite-wordpress` will start both the basic WordPress and multisite containers.\n\n\n### Running WordPress trunk, beta or RC\n\nIf you need WordPress trunk, a beta or a release candidate, there are two ways of going about that:\n\n- Switch using WP CLI:\n\n  ```bash\n  ./wp.sh core update --version=nightly\n  ```\n\nNote that you'll have to repeat this daily if you want to be on the latest nightly. If you want to switch back, do, note the `--force` because you're downgrading:\n\n  ```bash\n  ./wp.sh core update --version=5.4 --force\n  ./wp.sh core update --version=5.4 --force\n  ```\n\n- Install and use the [WordPress beta tester plugin](https://wordpress.org/plugins/wordpress-beta-tester/).\n  \n#### Setting up your plugins\n\nRun `./plugins.sh` - this will install default plugins to your container for easier debugging and developing.\nSimply clone, extract or download any plugins you want available in your environment into the `plugins` directory. They will be immediately visible inside your WordPress installation. Don't forget to activate them!\n\n#### Running WP CLI commands\n\nYou can run `./wp.sh` to run WP CLI commands. By default this will execute the command in the first running WordPress container ( created from this project ). However if the first argument is the name of a container it will specifically run in that container.\n\nFor example: `./wp.sh shell` will run `wp shell` in the first active WordPress installation. `./wp.sh woocommerce-wordpress cache flush` will run `wp cache flush` in the woocommerce-wordpresss installation.\n\n#### Mails and mailhog\n\nMailhog is a local catch-all for mails that are sent from local environments. To use it, use WordPress like you would normally. For example, create a new user and have the installation send an e-mail to the user. This will deliver the mail to your local Mailhog instance. To see this mail, open a new browsertab and navigate to [http://localhost:8025/](http://localhost:8025/). Here you will find all mails that are sent by the application.\n\nRemember that Mailhogs' memory is non-persistent. Closing down the container will wipe all stored e-mails.\n\n#### Updating your local WordPress installation\n\nThe local WordPress site won't be updated automatically. You have a few options to update your installation, with some pros and cons.\n\n1) The simplest way to update your WordPress installation is to click the update button in the WP admin. This process makes sure that you keep your data (like posts, plugins etc).\n2) A bit more forced way of updating (and resetting your database) can be accomplished with the following commands:\n\n```bash\n  ./clean.sh \u0026\u0026 \n  ./start.sh\n```\n\n1) If one of the methods fails, please contact the DevOps team. We can help you with updating specific docker images.\n\n_You might add the specific container argument after the ``./start.sh`` command._\n\n## WordPress Debugging\n\nThe docker environments come preconfigured with WordPress debugging on. If you want to enable Yoast debugging specifically, you can add the parameter `yoastdebug` to your URL. This will trigger the yoast debugging constants and show debugging logs on sitemaps and pretty print json-ld and such.\n\n### XDebug\n\nThis container is already preconfigured with XDebug. The only thing left to do is to configure your IDE and browser. See the following 2 headers.\n\n### PHPStorm\n\nIf you are using PHPStorm follow these instructions:\n\n1. Open up `Preferences -\u003e Languages \u0026 Frameworks -\u003e PHP -\u003e Servers`\n1. Click the `+` icon\n1. Name: Give it a recognizeable name or use the following Host.\n1. Host: `\u003cdomain name here\u003e` (default for this docker: `basic.wordpress.test`)\n1. Port: 80\n1. File/Directory `plugins/\u003cyour-plugin-name\u003e` maps to the absoulte path `/mnt/plugins/\u003cyour-plugin-name\u003e`.\n1. File/Directory `wordpress` maps to the absoulte path `/var/www/html`.\n1. Apply\n\nIn PHPStorm you can also add the `wordpress` directory to provide full WordPress indexation.\n\n### Visual Studio Code\n\nIf you are using VSCode simply copy/paste the following `launch.json` ( don't forget to edit `\u003cyour-plugin-name` ) which you can edit by running `Debug: open launch.json`:\n\n```json\n{\n    \"version\": \"0.2.0\",\n    \"configurations\": [\n        {\n            \"name\": \"Listen for XDebug\",\n            \"type\": \"php\",\n            \"request\": \"launch\",\n            \"port\": 9000,\n            \"pathMappings\": {\n                \"/var/www/html/wp-content/plugins/\u003cyour-plugin-name\u003e\": \"${workspaceRoot}\",\n                \"/var/www/html\": \"${workspaceRoot}/../../wordpress\",\n            },\n        }\n    ]\n}\n```\n\nThis assumes your plugin is the root of your opened VSCode project.\n\nAlso make sure you have the [XDebug extension installed](https://marketplace.visualstudio.com/items?itemName=felixfbecker.php-debug)!\n\n#### Browser\n\nFor Firefox you'll want to [install the Firefox XDebug helper](https://addons.mozilla.org/en-US/firefox/addon/xdebug-helper-for-firefox/).\nFor Chrome you'll want to [install the Chrome XDebug helper](https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc?hl=en).\n\nBoth of these do exactly the same. They add an icon to your URL bar where you can choose the XDebug settings for your request:\n\n- Setting it to `Debug` will make PHP pause on any breakpoints you've configured in your IDE ( provided you're listening to Debug connections ).\n- Setting it to `Profile` will make PHP time every function call and output a cachegrind file. These will be located in the `data/xdebug` directory.\n  - These can be opened with a tool called KCachegrind / QCachegrind. On Mac you can install it using `brew install qcachegrind`. On Linux you can usually install it using `sudo apt install kcachegrind`.\n- Setting it to `Trace` will make PHP output a full trace of every function call. These will also be located in the `data/xdebug` directory.\n  - By default parameters and return values are not included in traces. You can change these settings by changing your `config/php.ini`. For documentation on which values to change see [the XDebug documentation](https://xdebug.org/docs/execution_trace).\n  - For viewing these files with a GUI you could use [xdebug-trace-tree](https://github.com/splitbrain/xdebug-trace-tree). Cloning that project in the `wordpress` directory and visiting `http://local.wordpress.test/xdebug-trace-tree` should get you up and running.\n\n### Connecting to the database\n\nAll database ports are forwarded to localhost to make them easily accessible from various tools. You'll want to enter the following configuration:\n\n| Property | Value     |\n| -------- | --------- |\n| Host     | 127.0.0.1 |\n| Username | wordpress |\n| Password | wordpress |\n| Database | wordpress |\n\nThe port differs based on the installation you're running.\n\n| Site                      | Port |\n|---------------------------|------|\n| basic-wordpress           | 1987 |\n| woocommerce-wordpress     | 1988 |\n| multisite-wordpress       | 1989 |\n| standalone-wordpress      | 1990 |\n| multisitedomain-wordpress | 1991 |\n| nightly-wordpress         | 1992 |\n\n## Troubleshooting\n\n### WordPress is not installed (completely)\n\nThe first run after a make can fail. Quit all docker containers with `docker-compose down` and run `bash start.sh` again.\n\nIssue: [https://github.com/Yoast/plugin-development-docker/issues/11](https://github.com/Yoast/plugin-development-docker/issues/11)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoast%2Fplugin-development-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyoast%2Fplugin-development-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoast%2Fplugin-development-docker/lists"}