DDEV for existing wordpress site (with DDEV hooks)

README.md

UPDATE 2021: Checkout https://github.com/programmieraffe/ddev-pull-wp

This tutorial is for existing wordpress sites, which you want to edit/develop locally with ddev. Use case: Maybe you have a child-theme or plugin stored in git and you want to test it with the actual wordpress website.

1. Setup blank folder mylocalwpsite/, add .ddev/config.yaml
2. Adjust Line 19 in config.yaml and change it to the actual live URL of your wp site
3. Dump your sql-Database (e.g. phpMyAdmin), reimport it with ddev import-db (https://ddev.readthedocs.io/en/latest/users/cli-usage/#importing-a-database)
4. Download all wordpress files via sftp/ssh in your local folder (or use plugins such as https://wordpress.org/plugins/backwpup/), except your git tracked files (child-theme or plugin e.g.)
5. ddev start
6. Visit https://mylocalwpsite.ddev.site

⚠️ Important: Do not use "type=wordpress", this only works for usage of bedrock-boilerplate (see: https://ddev.readthedocs.io/en/latest/users/cli-usage/#wordpress-quickstart)

Tutorial is under public domain (https://creativecommons.org/publicdomain/zero/1.0/deed.de)

config.yaml

# this file should be in .ddev/config.yaml
name: mylocalwpsite
type: php
docroot: ""
php_version: "7.3"
webserver_type: apache-fpm
router_http_port: "80"
router_https_port: "443"
xdebug_enabled: false
additional_hostnames: []
additional_fqdns: []
provider: default
use_dns_when_possible: true
mysql_version: 8.0

hooks:
  post-import-db:
    # Update the URL of your project throughout your database after ddev import-db
    - exec: "wp search-replace https://YOUR-OFFICIAL-WP-URL.com/ https://mylocalwpsite.ddev.site"
  post-start:
    # Using wp-cli, overwrite wp-config.php with ddev values
    - exec: "wp config set DB_NAME db"
    - exec: "wp config set DB_USER db"
    - exec: "wp config set DB_PASSWORD db"
    - exec: "wp config set DB_HOST db"
    # this is optional, you could set more config values here (Cache, Logging, etc.)
    #- exec: "wp config set WP_DEBUG true --raw"


# This config.yaml was created with ddev version v1.15.3
# webimage: drud/ddev-webserver:v1.15.3
# dbimage: drud/ddev-dbserver-mariadb-10.2:v1.15.1
# dbaimage: phpmyadmin/phpmyadmin:5
# However we do not recommend explicitly wiring these images into the
# config.yaml as they may break future versions of ddev.
# You can update this config.yaml using 'ddev config'.

# Key features of ddev's config.yaml:

# name: <projectname> # Name of the project, automatically provides
#   http://projectname.ddev.site and https://projectname.ddev.site

# type: <projecttype>  # drupal6/7/8, backdrop, typo3, wordpress, php

# docroot: <relative_path> # Relative path to the directory containing index.php.

# php_version: "7.3"  # PHP version to use, "5.6", "7.0", "7.1", "7.2", "7.3", "7.4"

# You can explicitly specify the webimage, dbimage, dbaimage lines but this
# is not recommended, as the images are often closely tied to ddev's' behavior,
# so this can break upgrades.

# webimage: <docker_image>  # nginx/php docker image.
# dbimage: <docker_image>  # mariadb docker image.
# dbaimage: <docker_image>

# mariadb_version and mysql_version
# ddev can use many versions of mariadb and mysql
# However these directives are mutually exclusive
# mariadb_version: 10.2
# mysql_version: 8.0

# router_http_port: <port>  # Port to be used for http (defaults to port 80)
# router_https_port: <port> # Port for https (defaults to 443)

# xdebug_enabled: false  # Set to true to enable xdebug and "ddev start" or "ddev restart"
# Note that for most people the commands
# "ddev exec enable_xdebug" and "ddev exec disable_xdebug" work better,
# as leaving xdebug enabled all the time is a big performance hit.

# webserver_type: nginx-fpm  # Can be set to apache-fpm or apache-cgi as well

# timezone: Europe/Berlin
# This is the timezone used in the containers and by PHP;
# it can be set to any valid timezone,
# see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
# For example Europe/Dublin or MST7MDT

# additional_hostnames:
#  - somename
#  - someothername
# would provide http and https URLs for "somename.ddev.site"
# and "someothername.ddev.site".

# additional_fqdns:
#  - example.com
#  - sub1.example.com
# would provide http and https URLs for "example.com" and "sub1.example.com"
# Please take care with this because it can cause great confusion.

# upload_dir: custom/upload/dir
# would set the destination path for ddev import-files to custom/upload/dir.

# working_dir:
#   web: /var/www/html
#   db: /home
# would set the default working directory for the web and db services.
# These values specify the destination directory for ddev ssh and the
# directory in which commands passed into ddev exec are run.

# omit_containers: [db, dba, ddev-ssh-agent]
# Currently only these containers are supported. Some containers can also be
# omitted globally in the ~/.ddev/global_config.yaml. Note that if you omit
# the "db" container, several standard features of ddev that access the
# database container will be unusable.

# nfs_mount_enabled: false
# Great performance improvement but requires host configuration first.
# See https://ddev.readthedocs.io/en/stable/users/performance/#using-nfs-to-mount-the-project-into-the-container

# host_https_port: "59002"
# The host port binding for https can be explicitly specified. It is
# dynamic unless otherwise specified.
# This is not used by most people, most people use the *router* instead
# of the localhost port.

# host_webserver_port: "59001"
# The host port binding for the ddev-webserver can be explicitly specified. It is
# dynamic unless otherwise specified.
# This is not used by most people, most people use the *router* instead
# of the localhost port.

# host_db_port: "59002"
# The host port binding for the ddev-dbserver can be explicitly specified. It is dynamic
# unless explicitly specified.

# phpmyadmin_port: "8036"
# phpmyadmin_https_port: "8037"
# The PHPMyAdmin ports can be changed from the default 8036 and 8037

# mailhog_port: "8025"
# mailhog_https_port: "8026"
# The MailHog ports can be changed from the default 8025 and 8026

# webimage_extra_packages: [php7.3-tidy, php-bcmath]
# Extra Debian packages that are needed in the webimage can be added here

# dbimage_extra_packages: [telnet,netcat]
# Extra Debian packages that are needed in the dbimage can be added here

# use_dns_when_possible: true
# If the host has internet access and the domain configured can
# successfully be looked up, DNS will be used for hostname resolution
# instead of editing /etc/hosts
# Defaults to true

# project_tld: ddev.site
# The top-level domain used for project URLs
# The default "ddev.site" allows DNS lookup via a wildcard
# If you prefer you can change this to "ddev.local" to preserve
# pre-v1.9 behavior.

# ngrok_args: --subdomain mysite --auth username:pass
# Provide extra flags to the "ngrok http" command, see
# https://ngrok.com/docs#http or run "ngrok http -h"

# disable_settings_management: false
# If true, ddev will not create CMS-specific settings files like
# Drupal's settings.php/settings.ddev.php or TYPO3's AdditionalSettings.php
# In this case the user must provide all such settings.

# no_project_mount: false
# (Experimental) If true, ddev will not mount the project into the web container;
# the user is responsible for mounting it manually or via a script.
# This is to enable experimentation with alternate file mounting strategies.
# For advanced users only!

# provider: default # Currently either "default" or "pantheon"
#
# Many ddev commands can be extended to run tasks before or after the
# ddev command is executed, for example "post-start", "post-import-db",
# "pre-composer", "post-composer"
# See https://ddev.readthedocs.io/en/stable/users/extending-commands/ for more
# information on the commands that can be extended and the tasks you can define
# for them. Example:
#hooks:

Suggesting ddev config --project-type=php --mysql-version=8.0 would be better than providing the config.yaml.

Also, why use mysql 8? WP isn't particular about db servers is it? Mysql 8 is the most problem-prone version of all the database versions of mariadb and mysql IMO. I'd suggest not specifying database version or type, which would currently get mariadb 10.2

Suggesting ddev config --project-type=php --mysql-version=8.0 would be better than providing the config.yaml.

Also, why use mysql 8? WP isn't particular about db servers is it? Mysql 8 is the most problem-prone version of all the database versions of mariadb and mysql IMO. I'd suggest not specifying database version or type, which would currently get mariadb 10.2

Thanks for the comment! But the ddev hooks are not copied with ddev config?

Good point, most casual webspaces providers (at least in Germany) run mysql as far as i know, therefore I chose this as default.

Sorry, I didn't see the hooks in there.

But consider starting with a super-minimal config.yaml then, like this:

type: php
docroot: ""
webserver_type: apache-fpm
hooks:
  post-import-db:
    # Update the URL of your project throughout your database after ddev import-db
    - exec: "wp search-replace https://YOUR-OFFICIAL-WP-URL.com/ https://mylocalwpsite.ddev.site"
  post-start:
    # Install WordPress after start
    # Using wp-cli, overwrite wp-config.php with ddev values
    - exec: "wp config set DB_NAME db && wp config set DB_USER db && wp config set DB_PASSWORD db && wp config set DB_HOST db"

Why do you use apache-fpm?

BTW, the "wordpress" type works fine with any wordpress, including classicpress, so I'm not sure what trouble you had with it previously?

I just tested with WordPress 5.1, downloaded directly from wordpress.com, untarred it, ddev config, accepted defaults, ddev start, ddev launch, it worked out of the box.

So let's try to get sorted out why this was needed in the first place...

Thanks for the reply (again)!

Wordpress sites uses .htaccess for path rewrites, therefore nginx wouldn't work. (I try to be as close to the live server configuration as well, but thanks for the recommendation starting with a minimal ddev config. Depends on the use case of the dev I guess)

https://ddev.readthedocs.io/en/stable/users/cli-usage/#wordpress-quickstart refers to bedrock-boilerplate, which handles wordpress stuff quite different. Therefore I used type:php, but I did not read in detail what type= is even doing? Is this documented somewhere in https://ddev.readthedocs.io/, couldn't find it while looking for it?

The type determines what kind of settings files ddev will attempt to provide. It's hard to do completely on WP because there are so many different layouts for it. The quickstart chose bedrock because it's a more modern way to go, but that doesn't mean that ddev can't use it.

There's a general overview of how ddev works with settings files at https://ddev.com/ddev-local/controlling-cms-settings-files-in-ddev-local/

Nginx (with the config provided by ddev) works fine with WP as far as I've ever seen, I've never seen a problem with it. I think probably the provided configuration takes care of the things the .htaccess files also try to look at . However, your argument about .htaccess files and apache-fpm is reasonable. But I doubt you'll find any difference in practice.