Docker Configuration

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 variables
• nginx/ – Nginx configuration and SSL certificates
• php/ – PHP-FPM configuration
• mariadb/ – MariaDB configuration and data

Update Hosts File

Add or update entries in your system’s hosts file for local domain resolution:

wpstaging update-hosts-file

Or use the short alias:

wpstaging uhf

This command:

• Reads all configured sites
• Adds entries to /etc/hosts (Linux/macOS) or C:\Windows\System32\drivers\etc\hosts (Windows)
• Maps each hostname to its configured IP address

Generate Compose File

Regenerate the docker-compose.yml file for a specific site:

wpstaging generate-compose-file mysite.local

Or use the short alias:

wpstaging gcf mysite.local

Use 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.local

Or use the short alias:

wpstaging gdf mysite.local

This 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.local

Reinstall 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-ca

View Site Configuration

Display the environment variables and configuration for a site:

wpstaging compose-info mysite.local

This 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/path

Then use the same path for all subsequent commands:

wpstaging start --env-path=/custom/docker/path
wpstaging list --env-path=/custom/docker/path

Custom Compose File Path

Specify a custom location for the docker-compose.yml file:

wpstaging add mysite.local --compose-file=/custom/path/docker-compose.yml

Port 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

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.5

macOS IP Alias

On macOS, the CLI automatically creates IP aliases for addresses in the 127.3.2.x range. This requires sudo access.

Configuration Commands Summary

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

Next Steps

• Manage Docker WordPress Sites – Create and manage sites
• Control Docker Containers – Start, stop, and access containers
• Configuration and Environment – Global CLI configuration