This repository provides a development environment for WordPress development. The environment uses Docker Compose to ensure consistency and reproducibility across different development machines.
It was build specifically for Windows 11 with WSL2, but it should work on other platforms with minor adjustments.
- Windows with WSL2 (Debian recommended) - Provides the Linux environment needed for development
- Docker Desktop with WSL2 backend enabled - Manages our containers
- Visual Studio Code with Remote WSL extension - Enables efficient code editing
- Git for version control
- Basic command line knowledge
We use Make commands to simplify common operations. Here are the main commands available:
make up # Start the development environment
make clean # Remove all containers, volumes, and WordPress files
sudo make fix # Fix file permissions if you encounter access issues- Clone and prepare the environment:
git clone https://github.com/AEMuto/wp-docker-template.git <your-repo-name>
cd <your-repo-name>
# Copy and configure environment variables
cp .env.example .env
# Edit .env with your preferred settings- Set up permissions and user access:
# Add yourself to the www-data group
sudo usermod -aG www-data $USER
# IMPORTANT: Log out of WSL completely and log back in
exit
# Then reconnect to WSL and verify groups
groups # Should show www-data in the list- Start the environment:
make upOur Docker environment consists of several services working together:
-
wordpress: The main WordPress container- Runs Apache with PHP
- Mounts local directories for live development
- Configured with debugging enabled
-
db: MariaDB database- Persists data through Docker volumes
- Accessible on port 3306 for local tools
-
phpmyadmin: Database management- Provides web interface for database operations
- Available at http://localhost:8081
-
wp-cli: WordPress CLI tool- Runs initializati 7F7C on tasks
- Available for ongoing management tasks
.
├── docker-compose.yml # Container configuration
├── .env # Environment variables
├── plugins/ # Plugin development directory
├── themes/ # Theme development directory
├── uploads/ # Media uploads
├── wordpress/ # WordPress core files
├── scripts/ # Utility scripts
└── php-config/ # PHP configuration files
Understanding file permissions is crucial for this setup:
- Directories need 775 permissions (drwxrwxr-x)
- Files need 664 permissions (-rw-rw-r--)
- Files should be owned by your user and the www-data group
If you encounter permission issues, run:
sudo make fixThe WP-CLI container exits after initialization, but you can run commands anytime:
# Format: docker compose run --rm wp-cli wp <command>
# Examples:
docker compose run --rm wp-cli wp plugin list
docker compose run --rm wp-cli wp user listThe environment includes:
- WordPress debug logging (check wordpress/wp-content/debug.log)
- Xdebug configuration for VS Code
- PHP error reporting enabled
-
"Operation not permitted" errors:
- Run
sudo make fix - Verify you're in the www-data group
- Try cleaning and rebuilding:
make clean && make up
- Run
-
Database connection issues:
- Wait a few moments after startup
- Check logs:
docker compose logs db - Verify environment variables in .env
-
Container startup issues:
- Check port conflicts
- Verify Docker service is running
- Review logs:
docker compose logs
-
Version Control:
- Don't commit .env files
- Don't commit uploaded media
-
Development:
- Use WordPress coding standards
- Enable error reporting during development
- Test with WordPress debug mode enabled
-
Database:
- Use WP-CLI for database operations
- Backup before major changes
- Use proper database prefixes
-
Backups:
- Regularly back up your database
- Use version control for code
- You can use the following command to backup your database:
docker compose run --rm wp-cli wp db export /backups/backup-$(date +%F).sql
-
Development Credentials:
- Change default passwords in .env
- Never use development credentials in production
- Keep .env file secure and untracked
-
File Permissions:
- Don't use 777 permissions
- Maintain proper ownership
- Use group permissions properly
Remember. This is a development environment. Configure security measures appropriate for your deployment environment when moving to production.