{"id":31832071,"url":"https://github.com/vanbess/wp-docker-composer","last_synced_at":"2026-04-08T16:02:10.237Z","repository":{"id":318702745,"uuid":"1072427570","full_name":"vanbess/wp-docker-composer","owner":"vanbess","description":"Streamlined WordPress setup for Docker with built-in theme and plugin management via Composer/WPackagist","archived":false,"fork":false,"pushed_at":"2026-03-04T06:07:21.000Z","size":192,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T12:37:59.574Z","etag":null,"topics":["composer","development","docker","docker-compose","php","wordpress","wpackagist"],"latest_commit_sha":null,"homepage":"https://vanbess.github.io/wp-docker-composer/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vanbess.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-08T17:48:48.000Z","updated_at":"2025-10-25T11:04:23.000Z","dependencies_parsed_at":"2025-10-08T19:05:24.527Z","dependency_job_id":"336c0f8c-b994-4e0e-9d87-9ade787213e6","html_url":"https://github.com/vanbess/wp-docker-composer","commit_stats":null,"previous_names":["vanbess/wp-docker-composer"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/vanbess/wp-docker-composer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanbess%2Fwp-docker-composer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanbess%2Fwp-docker-composer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanbess%2Fwp-docker-composer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanbess%2Fwp-docker-composer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vanbess","download_url":"https://codeload.github.com/vanbess/wp-docker-composer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vanbess%2Fwp-docker-composer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31562697,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["composer","development","docker","docker-compose","php","wordpress","wpackagist"],"created_at":"2025-10-11T22:26:23.977Z","updated_at":"2026-04-08T16:02:10.231Z","avatar_url":"https://github.com/vanbess.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WordPress Docker Composer Environment\n\nA modern, professional WordPress development environment using Docker, Composer, and WPackagist for streamlined plugin and theme management.\n\n![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white)\n![WordPress](https://img.shields.io/badge/WordPress-21759B?style=for-the-badge\u0026logo=wordpress\u0026logoColor=white)\n![Composer](https://img.shields.io/badge/Composer-885630?style=for-the-badge\u0026logo=composer\u0026logoColor=white)\n![PHP](https://img.shields.io/badge/PHP-777BB4?style=for-the-badge\u0026logo=php\u0026logoColor=white)\n\n## 📑 Table of Contents\n\n- [Quick Start](#-quick-start)\n- [Common Issues \u0026 Troubleshooting](#️-common-issues--troubleshooting)\n- [Features](#-features)\n- [Architecture](#️-architecture)\n- [Automatic Permission Management](#-automatic-permission-management)\n- [Plugin \u0026 Theme Management](#-plugin--theme-management)\n- [Development Tools](#-development-tools)\n- [Error Filtering \u0026 Debug Management](#-error-filtering--debug-management)\n- [Must-Use Plugins](#-must-use-plugins)\n- [Backup \u0026 Restore](#-backup--restore)\n- [WP-CLI Commands](#wp-cli-commands)\n- [Popular Packages](#popular-packages)\n- [Environment Variables](#environment-variables)\n- [Advanced Troubleshooting](#advanced-troubleshooting)\n\n## � Quick Start\n\n```bash\n# Clone the repository\ngit clone https://github.com/vanbess/wp-docker-composer.git\ncd wp-docker-composer\n\n# Copy environment file and customize\ncp .env.example .env\n\n# Build containers (required for first-time setup)\ndocker compose build\n\n# Initialize the environment (automatic setup)\n./init-wordpress.sh\n\n# Or start manually\ndocker compose up -d\n./composer.sh install\n\n# Access your site\nopen http://localhost:8111\n```\n\n## ⚠️ Common Issues \u0026 Troubleshooting\n\n### First-Time Setup Issues\n\n#### Permission Script Not Found Error\n\nIf you see an error like:\n\n```\nOCI runtime exec failed: exec failed: unable to start container process: exec: \"/usr/local/bin/fix-permissions.sh\": stat /usr/local/bin/fix-permissions.sh: no such file or directory: unknown\n```\n\n**Solution:**\n\n```bash\n# Rebuild the WordPress container\ndocker compose build --no-cache wordpress\n\n# Recreate the container with the new image\ndocker compose down wordpress\ndocker compose up -d wordpress\n\n# Test that it's working\n./composer.sh install\n```\n\n#### WP-CLI Commands Hanging\n\nIf plugin/theme removal commands hang at the \"Running WP-CLI command with timeout\" step:\n\n**Solution:**\n\n```bash\n# Force stop any hanging containers\ndocker compose --profile tools down\n\n# Try the force-remove option instead\n./composer.sh plugin force-remove plugin-name\n```\n\n#### Git Ownership Warnings\n\nIf you see warnings like:\n\n```\nThe repository at \"/app\" does not have the correct ownership and git refuses to use it:\nfatal: detected dubious ownership in repository at '/app'\n```\n\nThis is automatically resolved in the latest version. If you still see this warning, ensure your containers are up to date:\n\n**Solution:**\n\n```bash\n# Rebuild composer service\ndocker compose build composer\n\n# Fix file ownership if needed\nsudo chown -R $USER:$USER composer.* vendor/\n```\n\n#### Container Build Issues\n\nIf this is your first time running the project or you've pulled recent updates:\n\n**Solution:**\n\n```bash\n# Always run this for first-time setup or after pulling updates\ndocker compose build\n\n# Then proceed with normal startup\ndocker compose up -d\n./composer.sh install\n```\n\n### Quick Fixes\n\n#### File Permission Issues\n\nIf you can't update plugins/themes through WordPress admin:\n\n```bash\n# Fix file permissions\n./composer.sh fix-permissions\n\n# Permissions are also auto-fixed after Composer operations\n```\n\n#### Reset Everything\n\n```bash\n# Stop containers and remove volumes\ndocker compose down -v\n\n# Remove vendor directory\nrm -rf vendor/\n\n# Rebuild containers from scratch\ndocker compose build --no-cache\n\n# Start fresh\ndocker compose up -d\n./composer.sh install\n```\n\n## ✨ Features\n\n- **🐳 Docker-based**: Isolated, reproducible development environment\n- **📦 Composer Integration**: Professional dependency management with WPackagist\n- **🛠️ Management Script**: Easy-to-use CLI for plugin/theme operations\n- **🔧 Auto-Permissions**: Automatic file permission fixes for Docker environments\n- **🔄 Version Control**: Pin, upgrade, downgrade plugins and themes with ease\n- **⚡ Fast Setup**: Get running in under 5 minutes with automatic initialization\n- **🛡️ Robust Error Handling**: Timeout protection and graceful fallbacks\n- **🔍 Diagnostics**: Built-in health checks and troubleshooting\n- **📚 Comprehensive Documentation**: Detailed guides and examples\n- **✅ Works Out of the Box**: No manual permission fixes needed (after initial container build)\n\n## 🏗️ Architecture\n\n### Services\n\n- **WordPress** (6.8 + PHP 8.3 + Apache)\n- **MariaDB** (10.11) - Fast, reliable database\n- **phpMyAdmin** - Database management interface\n- **Composer** - Dependency management\n- **WP-CLI** - WordPress command-line tools\n\n### Directory Structure\n\n```\nwp-docker-composer/\n├── docker-compose.yml          # Docker services configuration\n├── composer.json              # Composer dependencies\n├── composer.sh                # Management CLI script\n├── init-wordpress.sh           # One-command initialization script\n├── .env.example               # Environment template\n├── wp_data/                   # WordPress installation\n├── db_data/                   # Database files\n├── config/                    # Configuration files\n│   ├── php.ini               # PHP configuration\n│   └── mysql.cnf             # MySQL configuration\n├── docs/                     # Documentation\n└── scripts/                  # Utility scripts\n```\n\n## 🔧 Automatic Permission Management\n\nOne of the biggest pain points in Docker WordPress setups is file permissions. This environment **handles permissions automatically**:\n\n### What Gets Fixed Automatically\n\n- **File Ownership**: All WordPress files owned by `www-data` (the web server user)\n- **Directory Permissions**: Set to `755` (readable/executable by all, writable by owner)\n- **File Permissions**: Set to `644` (readable by all, writable by owner)\n- **Uploads Directory**: Fully writable for media uploads and plugin files\n- **wp-config.php**: Properly secured but updatable\n\n### When Permissions Are Fixed\n\n- **Automatically**: After every Composer operation (install, require, remove, etc.)\n- **On Startup**: When using `./composer.sh start` or `./init-wordpress.sh`\n- **On Demand**: Run `./composer.sh fix-permissions` anytime\n\n### Manual Permission Fixes\n\n```bash\n# Fix all WordPress file permissions\n./composer.sh fix-permissions\n\n# Start containers and auto-fix permissions\n./composer.sh start\n\n# Ensure everything is ready (containers + permissions)\n./composer.sh ready\n```\n\n## 📦 Plugin \u0026 Theme Management\n\n### Install Plugins\n\n```bash\n# Install a plugin from WPackagist\n./composer.sh plugin install contact-form-7\n./composer.sh plugin install yoast-seo\n./composer.sh plugin install akismet\n\n# Or use the full composer require command\n./composer.sh require wpackagist-plugin/contact-form-7\n```\n\n### Install Themes\n\n```bash\n# Install a theme from WPackagist\n./composer.sh theme install twentytwentyfour\n./composer.sh theme install astra\n\n# Or use the full composer require command\n./composer.sh require wpackagist-theme/twentytwentyfour\n```\n\n### Activate/Deactivate Plugins and Themes\n\n```bash\n# Activate a plugin\n./composer.sh plugin activate contact-form-7\n\n# Deactivate a plugin\n./composer.sh plugin deactivate contact-form-7\n\n# Activate a theme\n./composer.sh theme activate twentytwentyfour\n\n# List all plugins\n./composer.sh plugin list\n\n# List all themes\n./composer.sh theme list\n```\n\n### Update Dependencies\n\n```bash\n# Update all packages\n./composer.sh update\n\n# Check for outdated packages\n./composer.sh outdated\n```\n\n### Remove Plugins/Themes\n\n```bash\n# Safe removal (recommended) - tries to deactivate first, has fallbacks\n./composer.sh plugin remove contact-form-7\n\n# Force removal - skips deactivation, removes immediately\n./composer.sh plugin force-remove contact-form-7\n\n# Remove a theme\n./composer.sh theme remove twentytwentyfour\n```\n\n### Troubleshooting and Diagnostics\n\n```bash\n# Run comprehensive diagnostics\n./composer.sh doctor\n\n# Check container status, validate composer.json, show installed packages, etc.\n```\n\n**Note:** The safe removal method includes:\n\n1. **Timeout protection**: WP-CLI commands timeout after 10 seconds\n2. **Graceful fallbacks**: If deactivation fails, continues with removal\n3. **Manual cleanup**: If Composer fails, attempts manual directory removal\n4. **Error handling**: Clear feedback on each step\n\n### Version Management\n\n```bash\n# Check available versions\n./composer.sh plugin version wordfence\n./composer.sh theme version twentytwentyfour\n\n# Install specific version\n./composer.sh plugin install wordfence 7.10.0\n./composer.sh theme install twentytwentyfour 1.2.0\n\n# Downgrade to specific version\n./composer.sh plugin downgrade wordfence 7.9.0\n./composer.sh theme downgrade twentytwentyfour 1.1.0\n\n# Upgrade to latest version\n./composer.sh plugin upgrade wordfence\n./composer.sh theme upgrade twentytwentyfour\n\n# Check current installed versions\n./composer.sh show\n\n# Check for outdated packages\n./composer.sh outdated\n\n# Get package information\n./composer.sh info wpackagist-plugin/wordfence\n\n# Check why a package is installed\n./composer.sh why composer/installers\n```\n\n### Advanced Management\n\n```bash\n# Search for plugins/themes\n./composer.sh plugin search security\n./composer.sh theme search blog\n\n# Check plugin/theme status\n./composer.sh plugin status wordfence\n./composer.sh theme status twentytwentyfour\n\n# Validate composer.json\n./composer.sh validate\n\n# Clean and reinstall all dependencies\n./composer.sh clean\n```\n\n## 🛠️ Development Tools\n\n### Permission Management Script\n\nFor development environments, use the enhanced permission script that provides full read/write access:\n\n```bash\n# Set development-friendly permissions\n./scripts/set-dev-permissions.sh\n```\n\n**Features:**\n\n- ✅ Full read/write permissions (775/664) for development work\n- ✅ Special handling for log files (666) and cache directories (777)\n- ✅ Proper ownership (www-data:local-user via group permissions)\n- ✅ You can edit, save, and clear debug.log and other files\n\n**vs Standard Permissions:**\n\n- Standard: `scripts/fix-permissions.sh` (production-ready, more restrictive)\n- Development: `scripts/set-dev-permissions.sh` (full access for dev work)\n\n### Deploy Must-Use Plugins\n\nDeploy essential mu-plugins for enhanced debugging and error handling:\n\n```bash\n# Deploy all mu-plugins to WordPress\n./scripts/deploy-mu-plugins.sh\n```\n\nThis automatically copies and configures:\n\n## � Backup \u0026 Restore\n\nCreate and restore full backups of your WordPress installation, including database, files, and configuration. Perfect for recovering from breaking changes.\n\n### Creating Backups\n\n```bash\n# Create a backup (includes database, WordPress files, and configuration)\n./scripts/backup.sh create\n\n# List all available backups\n./scripts/backup.sh list\n```\n\n**What's Included:**\n\n- Database (all tables, triggers, routines)\n- WordPress files (wp_data directory)\n- Configuration files (.env, composer.json, docker-compose.yml)\n- Backup metadata (creation date, git branch/commit, hostname)\n\n### Restoring from Backup\n\n```bash\n# List available backups to find the right one\n./scripts/backup.sh list\n\n# Restore from a specific backup\n./scripts/backup.sh restore backups/myproject_20241025_120000.tar.gz\n```\n\n⚠️ **Warning:** Restoring will overwrite your current WordPress installation and database. Always verify you have the correct backup before proceeding.\n\n### Backup Management\n\n```bash\n# Clean up backups older than 30 days (frees disk space)\n./scripts/backup.sh cleanup 30\n\n# Clean up backups older than 7 days\n./scripts/backup.sh cleanup 7\n\n# Show full help and examples\n./scripts/backup.sh help\n```\n\n**Best Practices:**\n\n- Create backups **before making major changes** (plugin/theme updates, permissions changes, etc.)\n- Run cleanup periodically to manage disk space\n- Keep important backups on external storage for safety\n- Always verify a restore worked on a test environment first\n\n## �🚫 Error Filtering \u0026 Debug Management\n\nThe repository includes a sophisticated error filtering system to prevent debug log spam while maintaining visibility into real issues.\n\n### Features\n\n- **🔄 Duplicate Prevention**: Same error messages logged only once per 24 hours\n- **⚙️ Configurable Filtering**: Filter notices, warnings, and deprecated messages  \n- **🎯 Pattern Matching**: Blacklist/whitelist specific error patterns\n- **🧹 Automatic Cleanup**: Removes old cache entries automatically\n- **📊 Statistics**: View filtering stats via WP-CLI\n\n### Quick Setup\n\n```bash\n# Deploy the error filter system\n./scripts/deploy-mu-plugins.sh\n\n# Clear debug log to start fresh\necho \"\" \u003e wp_data/wp-content/debug.log\n\n# Set proper permissions\n./scripts/set-dev-permissions.sh\n```\n\n### Configuration\n\nCustomize filtering behavior in `mu-plugins/error-filter-config.php`:\n\n```php\n# Cache duration (24 hours default)\ndefine('ERROR_FILTER_CACHE_DURATION', 24 * 60 * 60);\n\n# Enable/disable filtering by type\ndefine('ERROR_FILTER_NOTICES', true);      # Filter notices\ndefine('ERROR_FILTER_WARNINGS', true);     # Filter warnings  \ndefine('ERROR_FILTER_DEPRECATED', true);   # Filter deprecated\n\n# Custom patterns (regex)\n$ERROR_FILTER_BLACKLIST = array(\n    '/Function _load_textdomain_just_in_time was called.*incorrectly/',\n    '/Translation loading for the.*domain was triggered too early/',\n);\n```\n\n### Monitoring\n\n```bash\n# View filter statistics\ndocker compose exec wordpress wp error-filter-stats\n\n# Check cache status\nls -la wp_data/wp-content/debug-cache.json\n\n# Monitor debug log in real-time\ntail -f wp_data/wp-content/debug.log\n\n## 📦 Must-Use Plugins\n\nMust-Use Plugins (mu-plugins) are automatically loaded WordPress plugins that cannot be deactivated through the admin interface. Perfect for essential functionality.\n\n### Available MU-Plugins\n\n| Plugin | Description | Auto-Deploy |\n|--------|-------------|-------------|\n| **Custom Error Filter** | Prevents debug log spam by filtering duplicate notices/warnings | ✅ |\n| **Error Filter Config** | Configuration file for customizing error filtering behavior | ✅ |\n\n### Repository Structure\n\n```\n\nmu-plugins/\n├── custom-error-filter.php     # Main error handler\n├── error-filter-config.php     # Configuration settings  \n├── README.md                   # Detailed documentation\n└── [your-plugin].php           # Add custom mu-plugins here\n\n```\n\n### Adding Custom MU-Plugins\n\n1. **Add your plugin** to the `mu-plugins/` directory\n2. **Deploy to WordPress**: `./scripts/deploy-mu-plugins.sh`\n3. **Set permissions**: `./scripts/set-dev-permissions.sh`\n4. **Commit to repository** for team sharing\n\n### Key Benefits\n\n- **🔒 Always Active**: Cannot be accidentally deactivated\n- **⚡ Early Loading**: Loaded before regular plugins and themes\n- **👥 Team Consistency**: Shared via repository across environments\n- **🛠️ Developer Tools**: Perfect for debugging and development utilities\n\n### Usage Examples\n\n```bash\n# Deploy all mu-plugins\n./scripts/deploy-mu-plugins.sh\n\n# Add custom mu-plugin\ncp my-custom-plugin.php mu-plugins/\n./scripts/deploy-mu-plugins.sh\n\n# View deployed plugins\nls -la wp_data/wp-content/mu-plugins/\n```\n\n**Note**: MU-plugins are loaded alphabetically by filename. Prefix with numbers for load order control (e.g., `01-critical.php`, `02-utilities.php`).\n\n```\n- Custom Error Filter (prevents debug log spam)\n- Error Filter Configuration (customizable settings)\n\n## WP-CLI Commands\n\nYou can run any WP-CLI command using:\n```bash\n./composer.sh wp \u003ccommand\u003e\n\n# Examples:\n./composer.sh wp core version\n./composer.sh wp user list\n./composer.sh wp option get siteurl\n./composer.sh wp db check\n```\n\n## Popular Packages\n\n### Popular Plugins Available via WPackagist\n\n- `contact-form-7` - Contact forms\n- `yoast-seo` - SEO optimization\n- `akismet` - Anti-spam\n- `wordfence` - Security\n- `jetpack` - All-in-one toolkit\n- `elementor` - Page builder\n- `woocommerce` - E-commerce\n- `classic-editor` - Classic WordPress editor\n- `duplicate-post` - Duplicate posts/pages\n- `wp-super-cache` - Caching\n\n### Popular Themes Available via WPackagist\n\n- `twentytwentyfour` - Latest default theme\n- `twentytwentythree` - Previous default theme\n- `astra` - Lightweight theme\n- `generatepress` - Fast theme\n- `oceanwp` - Multi-purpose theme\n\n## Environment Variables\n\nEdit `.env` file to customize:\n\n- Database credentials\n- WordPress debug settings\n- Port numbers\n- Admin user details\n\n## Advanced Troubleshooting\n\n### View Logs\n\n```bash\n# WordPress logs\ndocker compose logs wordpress\n\n# Database logs\ndocker compose logs db\n\n# All logs\ndocker compose logs\n```\n\n### Access Container Shell\n\n```bash\n# WordPress container\ndocker compose exec wordpress bash\n\n# Database container\ndocker compose exec db bash\n```\n\n### File Structure Reference\n\n```\nwp-docker-composer/\n├── docker-compose.yml     # Docker services configuration\n├── composer.json          # Composer dependencies\n├── composer.sh           # Helper script for Composer operations\n├── .env                  # Environment variables\n├── wp_data/              # WordPress files\n├── db_data/              # Database files\n├── config/               # Configuration files\n└── vendor/               # Composer packages (auto-generated)\n```\n\n---\n\n**Need help?** Check the troubleshooting sections above or open an issue on GitHub.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanbess%2Fwp-docker-composer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvanbess%2Fwp-docker-composer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvanbess%2Fwp-docker-composer/lists"}