The config.yml file located in the root of your project repository is used to configure your local Docker development environment. When you clone or download an existing site template from Seravo, it usually includes a pre-configured config.yml file.
If you start a new project from the blank Seravo/wordpress template, running the environment for the first time automatically generates a default config.yml based on config-sample.yml. Because config.yml contains no passwords or secrets, it is safe to commit to Git so your entire development team shares the same environment settings.
Prerequisites
Before customizing your local environment settings, ensure you have:
A local Docker development setup: Docker and Docker Compose (along with the optional
seravo-dockerCLI helper) installed on your workstation.A cloned project directory: Your site repository is cloned locally and contains the
config-sample.ymltemplate in the project root.Production SSH details (optional): If you plan to pull the database, plugins, or themes directly from production (
wp-pull-production-*), you need your site's SSH host, port, and configured SSH key.
Default and Custom config.yml Examples
The default config.yml generated for a blank project is minimal:
name: wordpress
development:
domains:
- wordpress.local
A more complete config.yml—including SSH connection details for production and staging, multiple local domains, and automated sync settings—looks like this:
name: mywpsite
production:
domain: example.seravo.com
ssh_port: 12345
staging:
domain: example.seravo.com
ssh_port: 23456
development:
domains:
- mywpsite.local
- another.local
- third.mywpsite.local
pull_production_db: never
pull_production_plugins: never
pull_production_themes: never
Editing and Applying Configuration Changes
After modifying config.yml, apply your changes by restarting the development environment from your project directory:
seravo-docker up
If you change the container identifier (name) or local domains (development.domains), recreate the containers to ensure network routing updates cleanly:
seravo-docker down && seravo-docker up
config.yml Reference
The table below outlines all supported configuration options in config.yml:
Setting | Default | Description |
|
| Internal site identifier used for naming Docker containers and networks, as well as the SSH username for sync commands (such as |
| – | Hostname of the production server from which data is pulled into the local environment. |
| – | Unique SSH port for the production environment. |
| – | Hostname of the staging (shadow) environment. |
| – | Unique SSH port for the staging environment. |
|
| List of local domains routed to the local Nginx container. |
|
| Determines whether the production database is pulled automatically on container startup ( |
|
| Determines whether production plugins are pulled automatically on container startup ( |
|
| Determines whether production themes are pulled automatically on container startup ( |
Note: On larger sites, setting pull_production_db: always can significantly slow down container startup and will overwrite any local database changes you have made. In most workflows, it is best to keep these values set to never and run wp-pull-production-db manually when needed.
WordPress Multisite in Local Development
WordPress Multisite networks require a few additional configuration steps to work smoothly inside the local Docker environment.
Defining DOMAIN_CURRENT_SITE
In production, wp-config.php typically contains a hardcoded primary domain in the DOMAIN_CURRENT_SITE constant. In local development, this constant must point to your local domain. Set it dynamically using the WP_ENV environment variable:
if ( 'development' === getenv( 'WP_ENV' ) ) {
define( 'DOMAIN_CURRENT_SITE', 'mywpsite.local' );
} else {
define( 'DOMAIN_CURRENT_SITE', 'example.com' );
}
Subdomains (Subdomain Multisite)
If you are running a subdomain-based Multisite network, add all subdomains to the development.domains list in config.yml before starting the container:
development:
domains:
- mywpsite.local
- site1.mywpsite.local
- site2.mywpsite.local
When you run wp-pull-production-db inside the container, the tool detects the subdomain setup and automatically converts production subdomains to their corresponding .local equivalents (e.g., site1.example.com → site1.mywpsite.local).
Note: If your network uses separate mapped domains (such as another-site.com), they are not converted automatically. Add them to development.domains (e.g., another-site.local) and run a manual search-and-replace across the network using wp search-replace 'https://another-site.com' 'http://another-site.local' --network.
Common Issues and Troubleshooting
seravo-docker upfails with a YAML syntax error: YAML files are strict about indentation. Make sure you use spaces (never tabs) for indentation and that list items (-) are properly indented beneathdomains:.A newly added domain in
development.domainsdoes not load in the browser: Savingconfig.ymlalone does not update network routing for an already running container. Runseravo-docker down && seravo-docker upin your project directory, and verify that your local DNS resolver (dnsmasq) orhostsfile resolves the.localdomain to127.0.0.1.wp-pull-production-*commands fail to connect to the production server: Verify that thenamefield inconfig.ymlmatches your site's SSH username and thatproduction.domainandproduction.ssh_portmatch your production environment details.Local database changes disappear when restarting the container: Check
config.ymlto ensurepull_production_dbis not set toalways.
See Also
A clearly structured config.yml keeps local development environments consistent across your team and simplifies syncing data with production. If you need assistance configuring your local environment or setting up Multisite development, our support team is happy to help at [email protected].
