A streamlined WordPress development environment with Docker/Podman support, comprehensive code quality tools, web-based management interface, and simplified management.
This release has been audit-hardened across the main matrix CLI and dashboard flows. The CLI now prefers live Docker/Podman state when Compose metadata is missing or stale, validates user input at the CLI/API boundary, and has smoke-tested fallbacks for site lifecycle, logs, database, WP-CLI, clone/reset, health check, and JSON output paths.
- Simplified Management: All-in-one
matrixscript for easy site management - Modern Web Interface: Beautiful dashboard at http://localhost:8500 with real-time status, keyboard shortcuts, and action modals
- Code Quality Tools: PHPStan, PHP CodeSniffer for WordPress development
- Development Tools: WP-CLI, Email testing (Mailpit), Xdebug, theme/plugin scaffolding, site presets, file watching
- Multi-Site Environment: Create and manage multiple WordPress instances
- Container Runtime Support: Full Docker and Podman support
- Real-time Dashboard: Live status bar, auto-refresh on actions, keyboard shortcuts (R to refresh, 1-6 for tabs, ? for help)
- Database Operations: Import/export SQL dumps, backups, restore
- Reliable Fallbacks: Status, logs, shell access, DB operations, and WP-CLI work against live containers even when Compose state is stale
- Resource Limits: Configure memory and CPU limits per site (
./matrix edit site --memory=512M --cpu=1) - Activity Log: Track all site operations in dashboard activity tab
- Docker OR Podman with docker-compose/podman-compose
- Node.js (for frontend web interface)
# Clone the repository
git clone https://github.com/barunTayenjam/wordpress-matrix.git
cd wordpress-matrix
# Make script executable
chmod +x matrix
# Start core services (database, redis, phpMyAdmin, frontend)
./matrix start
# Create your first site
./matrix create mysite
# Access the web dashboard
open http://localhost:8500
# Access your site (port shown after creation)
open http://localhost:8201After creating a site, the command output shows the direct access URL (e.g., http://localhost:8201).
- AGENTS.md - Comprehensive guide for AI agents and developers
- Web Dashboard - Interactive management interface at http://localhost:8500
# Create a new site (default PHP 8.3)
./matrix create blog
# Create a site with specific PHP version
./matrix create oldsite --php-version=7.4
./matrix create testsite --php-version=8.1
# List all sites
./matrix list
# Start core services (database, redis, phpMyAdmin, frontend)
./matrix start
# Start specific site
./matrix start blog
# Stop specific site
./matrix stop blog
# Restart a site
./matrix restart blog
# View site info
./matrix info blog
# Show site URL
./matrix url blog
# Remove a site
./matrix remove blog --yes
# Edit site configuration (PHP version, port, resources)
./matrix edit blog --php-version=8.2
./matrix edit blog --port=8203
./matrix edit blog --memory=512M --cpu=1# Backup a site
./matrix backup blog
# Restore from backup
./matrix restore blog backups/blog-20260501.tar.gz# Export database
./matrix export-db blog
# Export to specific file
./matrix export-db blog mydump.sql
# Import database
./matrix import-db blog dumpfile.sql# Run WP-CLI against a site without requiring a long-running wp-cli service
./matrix wp blog core version
./matrix wp blog plugin list
./matrix wp blog option get siteurlThe frontend at http://localhost:8500 provides:
- Start/Stop/Restart sites with one click
- Create new sites with PHP version selector
- Backup sites to tar.gz archives
- Edit PHP version, port, memory, and CPU
- Clone existing sites
- Reset to fresh WordPress install
- Export/Import SQL databases
- View site logs
- Delete sites
- Activity Log - Track all site operations
# Check all sites
./matrix check
# Check specific site
./matrix check blog
# Check specific path
./matrix check blog wp-content/themes/custom-theme# Run a full runtime health check
scripts/health-check.sh# Start web interface
./matrix frontend start
# Stop web interface
./matrix frontend stop
# Check frontend status
./matrix frontend status# Access WordPress container shell
./matrix shell wp
# Access database
./matrix shell db
# Access nginx container
./matrix shell nginx
# Check PHP version in running container
docker exec wp_blog php -v
# or with Podman:
podman exec wp_blog php -v- Dashboard: http://localhost:8500
Sites are accessible on sequentially assigned ports starting from 8201 (8200 is reserved for phpMyAdmin):
- First site: http://localhost:8201
- Second site: http://localhost:8202
- And so on...
The site URL is displayed after running ./matrix create <name> or ./matrix url <name>. You can also view all site URLs via the web dashboard.
- phpMyAdmin: http://localhost:8200
- Mailpit (Email Testing): http://localhost:8025
- Database: localhost:3306
# Email Testing (Mailpit)
./matrix mail # Opens email UI at http://localhost:8025
# Enable Xdebug for PHP debugging
./matrix xdebug mysite # Writes .user.ini Xdebug settings
# Scaffold themes and plugins
./matrix scaffold theme my-theme
./matrix scaffold plugin my-plugin
./matrix scaffold child my-child-theme
# View available site presets
./matrix preset
# Create site with preset
./matrix create myshop --preset=woocommerce
./matrix create myforum --preset=bbpress
# Watch files and clear OPcache on changes
./matrix watch mysite # Requires fswatch (brew install fswatch)# Supported PHP versions
./matrix create site74 --php-version=7.4 # Legacy WordPress testing
./matrix create site80 --php-version=8.0 # PHP 8.0 support
./matrix create site81 --php-version=8.1 # PHP 8.1 support
./matrix create site82 --php-version=8.2 # PHP 8.2 support
./matrix create site83 --php-version=8.3 # Latest stable (default)Each site can run a different PHP version, allowing you to:
- Test plugins/themes across multiple PHP versions
- Debug compatibility issues
- Gradually migrate legacy sites to newer PHP
- MySQL 8.0: Database server with health checks
- Redis: In-memory caching and session storage
- Nginx: High-performance web server for each site
- Multiple PHP Versions: Support for PHP 7.4, 8.0, 8.1, 8.2, 8.3 (default: 8.3)
- phpMyAdmin: Database management interface
- Site Management: Create, start, stop, restart, remove sites
- Backup & Restore: Full site backup/restore functionality
- Database Operations: Import/export SQL dumps
- Edit Configuration: Change PHP version, port, memory, and CPU per site
- Clone Sites: Duplicate existing sites
- Reset Sites: Reset to fresh WordPress installation
- View Logs: Real-time site log streaming
- Real-time Status: View all sites and services at a glance
- Filtering & Sorting: Search, filter, and sort site cards
- Safer Workflows: Modal-based clone, restore, import, and edit actions instead of browser prompts
- Code Quality: Run checks directly from the UI
- Modern Interface: Responsive, clean design with dark mode
# Services won't start
./matrix clean
./matrix start
# Database issues
./matrix status
scripts/health-check.sh
# Frontend issues
./matrix frontend restart
# Port conflicts
lsof -ti:8500 | xargs kill -9 # Clear frontend port# View frontend logs
tail -f logs/frontend.log
# View site logs
./matrix logs <site-name>
# View service logs
./matrix logs db
./matrix logs redis
./matrix logs phpmyadmin- Check Status:
./matrix status - View Dashboard: http://localhost:8500
- Review Documentation: Check AGENTS.md
wordpress-matrix/
├── matrix # Unified management script (works from any directory)
├── docker-compose.yml # Docker services configuration
├── frontend/ # Web management interface
│ ├── app.js # Express server
│ ├── public/ # Static assets & JS
│ └── views/ # Handlebars templates
├── scripts/ # Utility scripts
├── config/nginx/ # Nginx configurations
├── logs/ # Application logs
└── wp_*/ # WordPress site directories
Note: The
matrixscript is unified - it works from the project root or thefrontend/subdirectory. When run fromfrontend/, it automatically adjusts paths to the project root.
- Clone repository
- Make matrix executable:
chmod +x matrix - Start core services:
./matrix start - Create first site:
./matrix create mysite - Start your site:
./matrix start mysite - Open dashboard: http://localhost:8500
- Access your site at assigned port
- Create sites as needed
- Use web dashboard for visual management
- Run code quality checks before commits
- Use backups before major changes
| Service | Port |
|---|---|
| Frontend Dashboard | 8500 |
| phpMyAdmin | 8200 |
| WordPress Sites | 8201+ |
| Database | 3306 |
The current release was verified with:
- Shell syntax checks for
matrixand allscripts/*.sh - Frontend Jest suite: 11/11 tests passing
- Valid JSON output for
./matrix list --json,./matrix status --json, and./matrix info <site> --json - Runtime health check via
scripts/health-check.sh - Smoke tests for site lifecycle, database import/export, WP-CLI, cache, search-replace dry run, clone, reset, shell access, logs, and REST metadata
- Frontend runs as non-root user
- No docker socket mounting required
- Database credentials in
.envfile - Site name validation prevents conflicts
./matrix create mysite # Create site (PHP 8.3)
./matrix create mysite --php-version=8.1 # PHP 8.1
./matrix start # Start all services
./matrix start mysite # Start specific site
./matrix stop mysite # Stop specific site
./matrix restart mysite # Restart specific site
./matrix remove mysite --yes # Remove site
./matrix backup mysite # Backup site
./matrix restore mysite backups/myfile.tar.gz
./matrix export-db mysite # Export database
./matrix import-db mysite dump.sql
./matrix wp mysite core version
./matrix rest mysite # Show WordPress REST API metadata
./matrix edit mysite --php-version=8.2
./matrix logs mysite # View logs
./matrix check mysite # Code quality check
scripts/health-check.sh # Runtime health check
./matrix list # List sites
./matrix status # System status
./matrix frontend start # Start web UIMIT License - feel free to use this for your projects
Quick Start: chmod +x matrix && ./matrix start && ./matrix create mysite && ./matrix start mysite && open http://localhost:8500