Docker WordPress Local

This repository contains a local WordPress environment Docker setup based on:

• Linux Alpine
• PHP FPM
• nginx
• WP CLI
• Mailhog
• Xdebug

Composer, Node and PNPM are also included as part of the WordPress image.

Prerequisites

To use this local environment, you need:

1. Install Docker Desktop
2. Install mkcert: brew install mkcert

Usage

To use this image in an existing WordPress project:

1. Copy the following to your project root directory:

   1. The docker-compose.yml file.
   2. The .docker folder.
   3. The .env.sample file. Rename it to .env.

2. Edit the .env environment constants with your project details.

3. Go to your project root directory and move into the .docker folder:

   1. Create a certs folder and move into it: mkdir certs && cd certs
   2. Run mkcert -key-file cert-key.pem -cert-file cert.pem your-project.test localhost

4. Adjust your project wp-config.php file:

     // Database settings.
     define( 'DB_NAME', getenv( 'DB_NAME' ) );
     define( 'DB_USER', getenv( 'DB_USER' ) );
     define( 'DB_PASSWORD', getenv( 'DB_PASSWORD' ) );
     define( 'DB_HOST', getenv( 'DB_HOST' ) );
     define( 'DB_CHARSET', 'utf8' );
     define( 'DB_COLLATE', '' );
   
     // Site URL settings.
     define( 'WP_SITEURL', getenv( 'WP_SITEURL' ) );
     define( 'WP_HOME', getenv( 'WP_HOME' ) );

5. Ensure your /etc/hosts file contains 127.0.0.1 your-project.test or use a tool such as Dnsmasq

6. Run docker-compose up from the project root directory.

How to Use WP CLI

To use WP CLI, run docker-compose run --rm cli followed by the WP CLI command. For example: docker-compose run --rm cli plugin list.

Tip: You can create a shell alias: alias dwp='docker-compose run --rm cli'.

How to Use Composer

To execute Composer commands within the Docker environment, use the following syntax:

docker-compose run --rm wp composer [command]

If you need to run Composer commands in a specific directory, you can utilize the --working-dir option to designate the target directory. This is particularly useful when you want to manage dependencies located in a subdirectory of your container.

For example, to install Composer dependencies for the WordPress theme sc-starter-theme, run:

docker-compose run --rm wp composer install --working-dir=wp-content/themes/sc-starter-theme

How to Use PNPM

To execute PNPM commands within the Docker environment, use the following syntax:

docker-composer run --rm wp pnpm [command]

If you need to run PNPM commands in a specific directory, you can utilize the --dir option to designate the target directory. This is particularly useful when you want to manage dependencies located in a subdirectory of your container.

For example, to build assets for the WordPress theme sc-starter-theme, run:

docker-compose run --rm wp pnpm --dir=wp-content/themes/sc-starter-theme run build

How to Switch PHP Version

To switch the PHP version, change the related PHP_VERSION variable in the .env file. Available versions are 8.3, 8.2, 8.0 and 7.4. See Docker Hub wordpress image page for more info about available tags.

How to Enable HTTPS

By default, HTTPS is enabled. To make it work, you need to install mkcert library (see Prerequisite section) and generate SSL certificates (see step 3 of the Usage section).

How to Use Xdebug

Xdebug is enabled by default. To use it with Visual Studio Code, you have to include ?XDEBUG_SESSION=TRUE in the URL you are browsing, and you have to use this launch.json settings:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

You can enable/disable the Xdebug profiler by adding profile to the XDEBUG_MODE variable in .env, i.e. XDEBUG_MODE=debug,profile.

By default, requests end up in the ./profiling directory. The files begin with cachegrind.out. and are suffixed with the process ID.

How to Use Mailhog

To use Mailhog, you have to install and activate our mailhog plugin for WordPres. Then you can simply visit http://your-project.test:8025.