Preconfigured Docker Dev Environment

Overview

The setup uses VS Code Dev Containers to spin up a complete WordPress environment.

Getting Started

Prerequisites

1. Docker Desktop installed and running.
2. VS Code installed.
3. Dev Containers extension for VS Code.

Installation

To create a new project with the Dev Container pre-configured:

npx -y generator-chisel --devcontainer

npx -y generator-chisel --devcontainer

Starting the environment

1. Open your project folder in VS Code.
2. You should see a prompt: “Folder contains a Dev Container configuration file. Reopen to develop in a container.”
3. Click Reopen in Container.

Alternatively: Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run “Dev Containers: Reopen in Container”. VS Code will build the images and start the containers. This may take a few minutes the first time.

Automatic Configuration

Once the container starts, the post-create-command.sh script automatically runs to:

1. Install dependencies: Runs npm install and composer install.
2. Configure WordPress: Generates wp-config-local.php with correct database credentials for the container network.
3. Build assets: Runs npm run build.
4. Fix permissions: Ensures file ownership is correct for the wordpress user.

VS Code Integration

The environment comes with pre-configured VS Code extensions and settings (.devcontainer/devcontainer.json), including:

• ESLint & Prettier for code quality.
• Stylelint for SCSS.
• PHP Intelephense for autocompletion.
• EditorConfig for consistent formatting.

Usage

Local Server

Your site will be available at: http://localhost:3000 (or the port defined in CHISEL_PORT)

Terminal

The integrated terminal in VS Code runs inside the container. You can run all commands directly:

# Run WP-CLI commands
wp plugin list

# Run Composer
composer install

# Run NPM scripts
npm run dev

# Run WP-CLI commands
wp plugin list

# Run Composer
composer install

# Run NPM scripts
npm run dev

Database Access

• Host: db
• User: mariadb
• Password: mariadb
• Database: mariadb

Configuration & Debugging

Editing wp-config.php

In the Docker environment, wp-config.php automatically loads wp-config-local.php if it exists. This file is generated by Chisel but can be edited directly to change settings.

To enable debug logs or other constants:

1. Open wp-config-local.php.
2. Modify the constants as needed.

Example for full debugging:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false ); // Hide errors from screen, log them instead

// Required for Chisel's fast refresh functionality
define( 'SCRIPT_DEBUG', true );
define( 'WP_ENVIRONMENT_TYPE', 'development' );

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false ); // Hide errors from screen, log them instead

// Required for Chisel's fast refresh functionality
define( 'SCRIPT_DEBUG', true );
define( 'WP_ENVIRONMENT_TYPE', 'development' );

Note: If you accidentally delete or break this file, you can regenerate it with the correct Docker database credentials by running:

npm run wp-config -- --devcontainer

npm run wp-config -- --devcontainer

Changing PHP/WP Version

Edit .devcontainer/docker-compose.yml:

args:
  BASE_IMAGE_VERSION: 6.9.0-php8.3 # Change to desired version

args:
  BASE_IMAGE_VERSION: 6.9.0-php8.3 # Change to desired version

Changing Port

Edit .devcontainer/docker-compose.yml and .devcontainer/Dockerfile.

Node Modules & Vendor

node_modules and vendor directories are mounted as named volumes to improve performance and prevent permission issues between the host OS and the container.