wp-docker-compose-stack

A custom docker-compose stack for WordPress

Hand-write a compose stack when you need services the official tooling doesn't model: Redis object cache, SMTP capture, custom PHP extensions, production-like topology. Default to wp-env first (see wp-env-local-dev) — it covers plain plugin/block development with less to maintain. This skill is the escape hatch, grounded against a fully booted and verified stack (WordPress + MariaDB + Redis + Mailpit + wp-cli, drop-in connected, mail captured). The complete tested files are bundled under examples/.

When to use this skill

• Writing or reviewing a docker-compose.yml for WordPress development.
• Adding Redis (object cache), Mailpit (mail capture), Xdebug, or php.ini overrides to a WP container setup.
• Debugging "my WORDPRESS_CONFIG_EXTRA / WP_REDIS_HOST is ignored" or "wp-cli sees different config than the site".
• wp_mail silently fails inside a container.
• A team needs a production-like local topology that wp-env can't express.

The config model: env is read at request time

This is the load-bearing fact of the official wordpress image, and the source of most broken stacks. The generated wp-config.php does not bake values in — it calls getenv_docker() on every request, and WORDPRESS_CONFIG_EXTRA is eval'd from the environment at runtime.

Consequence (verified by hitting it): a wp-cli container sharing the same volume gets none of that config unless it has the same environment variables. Our wp redis enable failed with Connection refused [tcp://127.0.0.1:6379] because only the wordpress service had WORDPRESS_CONFIG_EXTRA with WP_REDIS_HOST — the wp-cli service silently fell back to defaults. Share the block with a YAML anchor:

x-wp-environment: &wp-environment
  WORDPRESS_DB_HOST: db
  WORDPRESS_DB_USER: wordpress
  WORDPRESS_DB_PASSWORD: wordpress
  WORDPRESS_DB_NAME: wordpress
  WORDPRESS_CONFIG_EXTRA: |
    define( 'WP_REDIS_HOST', 'redis' );
    if ( ! defined( 'WP_DEBUG' ) ) { define( 'WP_DEBUG', true ); }
    define( 'WP_DEBUG_LOG', true );

services:
  wordpress:
    environment: *wp-environment
  wpcli:
    environment: *wp-environment