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 exec 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 exec wp composer install --working-dir=wp-content/themes/sc-starter-theme

How to Use Package Managers

Our WordPress image comes with all the major package managers pre-installed: bun, pnpm, yarn and npm.

To execute a package manager commands within the Docker environment, use the following syntax:

docker-compose exec wp <package-manager> <command>

For example:

docker-compose exec wp bun run build

Some package managers allow commands to be run in a specific directory. For instance, you can use options like --dir (for pnpm), --cwd (for bun, yarn) or --prefix (for npm) 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 exec wp bun --cwd 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 comes pre-installed and activated in the wp and cli containers, allowing debugging of website requests and WP-CLI commands.

To use Xdebug 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}"
      }
    }
  ]
}

As an alternative to the ?XDEBUG_SESSION=TRUE parameter in the URL, you can use a browser extension like Xdebug Helper for Chrome, Firefox, Edge or Xdebug Key for Safari,

To initiate Xdebug for WP-CLI commands, you need to set environment variable XDEBUG_SESSION=true inside the cli Docker container. E.g.

docker-compose run -e XDEBUG_SESSION=true --rm cli wp_cli_command_to_debug

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

Profiling data files are, by default, stored in the ./profiling directory. These files are prefixed with cachegrind.out. and appended with the respective 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 https://your-project.test:8025.