{"id":29525254,"url":"https://github.com/heymaia-io/wordpress-docker-dev","last_synced_at":"2026-04-04T21:33:21.075Z","repository":{"id":304098421,"uuid":"1017747483","full_name":"heymaia-io/wordpress-docker-dev","owner":"heymaia-io","description":"🐳 A complete Docker-based WordPress development environment with local data persistence, Xdebug, WP-CLI, and easy plugin mounting. Ready to use in seconds!","archived":false,"fork":false,"pushed_at":"2025-07-11T04:13:49.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-11T08:27:37.644Z","etag":null,"topics":["bash-scripts","dev-environment","development-environment","development-tools","docker","docker-compose","local-development","mariadb","php","phpmyadmin","plugin-development","theme-development","wordpress","wordpress-development","wordpress-docker","wordpress-sandbox","wp-cli","xdebug"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heymaia-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-07-11T03:27:46.000Z","updated_at":"2025-07-11T04:21:50.000Z","dependencies_parsed_at":"2025-07-11T08:27:41.949Z","dependency_job_id":null,"html_url":"https://github.com/heymaia-io/wordpress-docker-dev","commit_stats":null,"previous_names":["heymaia-io/local-wp-environment"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/heymaia-io/wordpress-docker-dev","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heymaia-io%2Fwordpress-docker-dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heymaia-io%2Fwordpress-docker-dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heymaia-io%2Fwordpress-docker-dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heymaia-io%2Fwordpress-docker-dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heymaia-io","download_url":"https://codeload.github.com/heymaia-io/wordpress-docker-dev/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heymaia-io%2Fwordpress-docker-dev/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31415110,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: 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":["bash-scripts","dev-environment","development-environment","development-tools","docker","docker-compose","local-development","mariadb","php","phpmyadmin","plugin-development","theme-development","wordpress","wordpress-development","wordpress-docker","wordpress-sandbox","wp-cli","xdebug"],"created_at":"2025-07-16T19:02:06.177Z","updated_at":"2026-04-04T21:33:21.056Z","avatar_url":"https://github.com/heymaia-io.png","language":"Shell","readme":"# WordPress Development Environment\n\nThis is a Docker-based WordPress development environment for general WordPress development.\n\n## Features\n\n- WordPress 6.8.2 with PHP 8.4\n- MariaDB 11.4.7 (matching your hosting server)\n- PHPMyAdmin for database management\n- WP-CLI for command-line WordPress management\n- Xdebug for debugging\n- Live mounting support for plugin development\n- Custom WordPress configuration for development\n- Easy plugin mounting and management\n- Local data storage (not tracked in Git)\n- **Dual user setup:** Automatic creation of Admin and Editor users for role-based testing\n\n## Quick Start\n\n1. **Start the environment:**\n\n   ```bash\n   ./manage.sh start\n   ```\n\n2. **Access your sites:**\n\n   - WordPress: http://localhost:8080\n   - PHPMyAdmin: http://localhost:8081\n\n3. **Login credentials:**\n   - **Admin:** Username: `admin`, Password: `admin_password123`\n   - **Editor:** Username: `editor`, Password: `editor_password123`\n\n## Environment Configuration\n\nYou can customize the environment by creating a `.env` file:\n\n```bash\ncp .env.example .env\n```\n\nThen edit `.env` to customize:\n\n```bash\n# Port Configuration\nWORDPRESS_PORT=8080\nPHPMYADMIN_PORT=8081\n\n# WordPress Site Configuration\nWORDPRESS_URL=http://localhost:8080\nWORDPRESS_TITLE='My Development Site'\n\n# Admin User Configuration\nWORDPRESS_ADMIN_USER=admin\nWORDPRESS_ADMIN_PASSWORD=admin_password123\nWORDPRESS_ADMIN_EMAIL=admin@localhost.dev\n\n# Editor User Configuration (optional - will be created automatically)\nWORDPRESS_EDITOR_USER=editor\nWORDPRESS_EDITOR_PASSWORD=editor_password123\nWORDPRESS_EDITOR_EMAIL=editor@localhost.dev\n```\n\nAll changes in `.env` are automatically applied when you run `./manage.sh start`!\n\n## User Roles \u0026 Testing\n\nThe environment automatically creates two users for comprehensive testing:\n\n### Administrator User\n\n- **Username:** `admin` (configurable via `WORDPRESS_ADMIN_USER`)\n- **Password:** `admin_password123` (configurable via `WORDPRESS_ADMIN_PASSWORD`)\n- **Capabilities:** Full site management, plugin installation, theme editing, user management\n- **Use for:** Site configuration, plugin development, admin-only features\n\n### Editor User\n\n- **Username:** `editor` (configurable via `WORDPRESS_EDITOR_USER`)\n- **Password:** `editor_password123` (configurable via `WORDPRESS_EDITOR_PASSWORD`)\n- **Capabilities:** Content creation, post/page management, media uploads (limited admin access)\n- **Use for:** Testing content workflows, role-based plugin features, editor-specific functionality\n\nThis dual-user setup allows you to test plugins and themes with different permission levels without manually creating users or switching roles.\n\n## Development Customizations\n\nNeed to mount custom plugins or themes? Create a development override file:\n\n```bash\n# Copy the main compose file to create a development version\ncp docker-compose.yml docker-compose.dev.yml\n\n# Edit docker-compose.dev.yml to add your plugin/theme mounts\n# Example: Add volumes under the wordpress and wpcli services:\n# services:\n#   wordpress:\n#     volumes:\n#       - ./data/wordpress:/var/www/html\n#       - ../my-plugin:/var/www/html/wp-content/plugins/my-plugin\n#       - ../my-theme:/var/www/html/wp-content/themes/my-theme\n#       # ... other existing volumes\n#   wpcli:\n#     volumes:\n#       - ./data/wordpress:/var/www/html\n#       - ../my-plugin:/var/www/html/wp-content/plugins/my-plugin\n#       - ../my-theme:/var/www/html/wp-content/themes/my-theme\n#       # ... other existing volumes\n```\n\n**Benefits:**\n\n- ✅ `docker-compose.dev.yml` is ignored by Git (safe to customize)\n- ✅ `manage.sh` automatically detects and uses the dev file when present\n- ✅ No risk of accidentally committing your local plugin mounts\n- ✅ Keep the original `docker-compose.yml` clean for the public repo\n\n## Running Multiple Instances\n\nNeed to test plugins with multiple WordPress sites (e.g., master/client setup)? Simply clone the repository multiple times and configure different ports:\n\n```bash\n# Clone for master instance\ngit clone https://github.com/heymaia-io/wordpress-docker-dev.git wordpress-master\ncd wordpress-master\ncp .env.example .env\n# Keep default ports (8080, 8081)\n./manage.sh start\n# Master: http://localhost:8080, PHPMyAdmin: http://localhost:8081\n\n# Clone for client instance\ngit clone https://github.com/heymaia-io/wordpress-docker-dev.git wordpress-client\ncd wordpress-client\ncp .env.example .env\n```\n\n**Configure different ports for client instance** by editing `.env`:\n\n```bash\n# Edit .env file\nWORDPRESS_PORT=8090\nPHPMYADMIN_PORT=8091\nWORDPRESS_URL=http://localhost:8090\n```\n\nThen start the client:\n\n```bash\n./manage.sh start\n# Client: http://localhost:8090, PHPMyAdmin: http://localhost:8091\n```\n\n**Benefits of this approach:**\n\n- ✅ No need to edit docker-compose.yml manually\n- ✅ All configuration in one place (.env file)\n- ✅ Easy to manage multiple instances\n- ✅ Each instance completely isolated\n\n## Management Commands\n\nThe `manage.sh` script provides easy management of your development environment:\n\n```bash\n./manage.sh start     # Start the environment\n./manage.sh stop      # Stop the environment\n./manage.sh restart   # Restart the environment\n./manage.sh status    # Show status\n./manage.sh logs      # Show container logs\n./manage.sh clean     # Clean environment (removes all data)\n./manage.sh wpcli     # Run WP-CLI commands\n```\n\n## Plugin Development\n\nTo develop plugins, you can mount them into the WordPress instance by adding volumes to the `docker-compose.yml` file:\n\n```yaml\nvolumes:\n  - ./data/wordpress:/var/www/html\n  - ./your-plugin:/var/www/html/wp-content/plugins/your-plugin\n```\n\nAny changes you make to mounted plugin files will be immediately reflected in WordPress.\n\nTo activate your plugin:\n\n```bash\n./manage.sh wpcli plugin activate your-plugin-name\n```\n\n## Customizing for Your Project\n\n### Mounting Your Plugins\n\nTo mount your own plugins for development, edit the `docker-compose.yml` file and add volume mounts under both the `wordpress` and `wpcli` services:\n\n```yaml\nvolumes:\n  - ./data/wordpress:/var/www/html\n  - ./my-plugin:/var/www/html/wp-content/plugins/my-plugin\n```\n\n### Changing Admin Credentials\n\nYou can customize the WordPress admin credentials by editing the `manage.sh` file in the `setup_wordpress()` function. Look for these lines:\n\n```bash\n--admin_user=\"admin\" \\\n--admin_password=\"admin_password123\" \\\n--admin_email=\"admin@localhost.dev\" \\\n```\n\n### Port Configuration\n\nIf ports 8080 or 8081 are already in use on your system, you can change them in `docker-compose.yml`:\n\n```yaml\nports:\n  - '8090:80' # WordPress will be available on http://localhost:8090\n```\n\n## Local Data Storage\n\nThis environment stores all data locally in the `data/` folder:\n\n- **WordPress files:** `data/wordpress/` - Contains all WordPress core files, plugins, themes, and uploads\n- **Database files:** `data/mysql/` - Contains the MariaDB database files\n\n**Benefits:**\n\n- Faster performance compared to Docker volumes\n- Easy to backup - just copy the `data/` folder\n- Persistent data that survives container recreation\n- Easy to inspect and debug files\n\n**Git Integration:**\n\n- The `data/` folder structure is tracked in Git\n- The actual content is ignored via `.gitignore`\n- Fresh clones will have empty data folders ready for use\n\n## Custom WordPress Configuration\n\nThe following custom settings are automatically applied:\n\n```php\ndefine('UPLOADS', 'wp-content/media-files');\ndefine('WP_AUTO_UPDATE_CORE', false);\ndefine('DISALLOW_FILE_EDIT', true);\n```\n\nPlus development-friendly settings like WP_DEBUG enabled.\n\n## Database Access\n\n- **PHPMyAdmin:** http://localhost:8081\n- **Database:** wordpress\n- **Username:** wordpress\n- **Password:** wordpress_password\n- **Root password:** root_password\n\n## WP-CLI Examples\n\n```bash\n# List all plugins\n./manage.sh wpcli plugin list\n\n# Install a plugin\n./manage.sh wpcli plugin install contact-form-7\n\n# User management (Admin and Editor users are created automatically)\n./manage.sh wpcli user list\n./manage.sh wpcli user create developer dev@example.com --role=administrator\n\n# Export/Import database\n./manage.sh wpcli db export backup.sql\n./manage.sh wpcli db import backup.sql\n```\n\n## Debugging\n\nXdebug is pre-configured and ready to use:\n\n- **Port:** 9003\n- **IDE Key:** VSCODE\n- **Client Host:** host.docker.internal\n\nConfigure your IDE to listen on port 9003 for Xdebug connections.\n\n## Troubleshooting\n\n1. **Docker not running:** Make sure Docker Desktop is running\n2. **Port conflicts:** If ports 8080 or 8081 are in use, modify the docker-compose.yml\n3. **Permission issues:** The containers run as user 33 (www-data)\n4. **Plugin not visible:** Ensure your plugin folder is properly mounted in docker-compose.yml\n\n## Clean Start\n\nTo completely reset the environment:\n\n```bash\n./manage.sh clean\n./manage.sh start\n```\n\nThis will remove all WordPress data and database, giving you a fresh installation.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheymaia-io%2Fwordpress-docker-dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheymaia-io%2Fwordpress-docker-dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheymaia-io%2Fwordpress-docker-dev/lists"}