WP Staging CLI generates Docker configuration files automatically when you create sites. This guide covers advanced configuration options and manual file generation.
Configuration Files
When you create a site, WP Staging CLI generates these files in ~/wpstaging/sites/<hostname>/:
docker-compose.yml– Main Docker Compose configuration.env– Environment variablesnginx/– Nginx configuration and SSL certificatesphp/– PHP-FPM configurationmariadb/– MariaDB configuration and data
Update Hosts File
Add or update entries in your system’s hosts file for local domain resolution:
wpstaging update-hosts-fileOr use the short alias:
wpstaging uhfThis command:
- Reads all configured sites
- Adds entries to
/etc/hosts(Linux/macOS) orC:\Windows\System32\drivers\etc\hosts(Windows) - Maps each hostname to its configured IP address
Note: This command requires elevated privileges (sudo on Linux/macOS, Administrator on Windows).
Generate Compose File
Regenerate the docker-compose.yml file for a specific site:
wpstaging generate-compose-file mysite.localOr use the short alias:
wpstaging gcf mysite.localUse this when you need to:
- Reset the Compose file to defaults
- Update after manual configuration changes
- Troubleshoot Docker issues
Generate Docker Files
Regenerate all Docker configuration files for a site:
wpstaging generate-docker-file mysite.localOr use the short alias:
wpstaging gdf mysite.localThis regenerates:
- docker-compose.yml
- Nginx configuration
- PHP-FPM configuration
- Environment file
SSL Certificate Management
WP Staging CLI uses mkcert to generate locally-trusted SSL certificates.
Reinstall Certificate
If you have certificate issues, regenerate the SSL certificate for a site:
wpstaging reinstall-cert mysite.localReinstall Certificate Authority
If certificates are not trusted by your browser, reinstall the mkcert CA to your system trust store:
wpstaging reinstall-cert mysite.local --reinstall-caNote: The --reinstall-ca flag requires elevated privileges to install the CA certificate in your system’s trust store.
View Site Configuration
Display the environment variables and configuration for a site:
wpstaging compose-info mysite.localThis shows the parsed docker-compose.yml settings including:
- Container names and images
- Port mappings
- Volume mounts
- Environment variables
Custom Environment Path
By default, all Docker environments are stored in ~/wpstaging. You can specify a custom path:
wpstaging add mysite.local --env-path=/custom/docker/pathThen use the same path for all subsequent commands:
wpstaging start --env-path=/custom/docker/path
wpstaging list --env-path=/custom/docker/pathCustom Compose File Path
Specify a custom location for the docker-compose.yml file:
wpstaging add mysite.local --compose-file=/custom/path/docker-compose.ymlPort Configuration
If default ports conflict with other services, customize them when creating sites:
wpstaging add mysite.local \
--http-port=8080 \
--https-port=8443 \
--db-port=3307 \
--mailpit-http-port=8026| Flag | Default | Description |
|---|---|---|
--http-port | 80 | Nginx HTTP port |
--https-port | 443 | Nginx HTTPS port |
--db-port | 3306 | MariaDB port |
--mailpit-http-port | 8025 | Mailpit web interface port |
IP Address Configuration
By default, sites use IP addresses in the 127.3.2.x range (loopback addresses). This allows multiple sites to run simultaneously on the same ports (80/443).
wpstaging add mysite.local --container-ip=127.3.2.5macOS IP Alias
On macOS, the CLI automatically creates IP aliases for addresses in the 127.3.2.x range. This requires sudo access.
Tip: To avoid repeated password prompts on macOS, set up passwordless sudo for the ifconfig command. See the FAQ for detailed instructions.
Configuration Commands Summary
| Command | Alias | Description |
|---|---|---|
update-hosts-file | uhf | Update hosts file with site entries |
generate-compose-file | gcf | Regenerate docker-compose.yml |
generate-docker-file | gdf | Regenerate all Docker config files |
reinstall-cert | – | Regenerate SSL certificate |
compose-info | – | Display site configuration |
Directory Structure
The default environment directory structure:
~/wpstaging/
├── sites/
│ └── mysite.local/
│ ├── docker-compose.yml
│ ├── .env
│ ├── www/ # WordPress files
│ ├── nginx/
│ │ ├── nginx.conf
│ │ └── ssl/
│ │ ├── mysite.local.crt
│ │ └── mysite.local.key
│ ├── php/
│ │ └── php.ini
│ └── mariadb/
│ └── data/ # Database files
└── shared/
└── mkcert/ # CA certificates
Reconfigure a Site Without Reinstalling
The reconfigure command regenerates a site’s Docker setup and restarts it — the WordPress files and database stay untouched. It accepts the same web server, database, and port options as add:
wpstaging reconfigure mysite.local --use-apachewpstaging reconfigure mysite.local --https-port=8443 --db-port=3307When the HTTPS port changes, the WordPress site address is updated to the new port automatically.
Web Server and Database Choices
Sites are generated with nginx and MariaDB by default. Create a site on Apache with --use-apache, or on MySQL with --use-mysql and --db-version — and move an existing site between them with reconfigure. When a site runs on Apache or MySQL, the generated configuration folder carries the matching files instead. Details: Choose Apache or MySQL for Local WordPress Sites.
Next Steps
- Manage Docker WordPress Sites – Create and manage sites
- Control Docker Containers – Start, stop, and access containers
- Configuration and Environment – Global CLI configuration
- Choose Apache or MySQL for Local Sites – Apache, MySQL, and exact database versions