Skip to main content

Local Environment Configuration

Learn how to configure your Seravo project's local development environment using the config.yml file. Manage local domains, SSH details, automated syncing, and WordPress Multisite settings.

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-docker CLI helper) installed on your workstation.

  • A cloned project directory: Your site repository is cloned locally and contains the config-sample.yml template 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

name

wordpress

Internal site identifier used for naming Docker containers and networks, as well as the SSH username for sync commands (such as wp-pull-production-db).

production.domain

–

Hostname of the production server from which data is pulled into the local environment.

production.ssh_port

–

Unique SSH port for the production environment.

staging.domain

–

Hostname of the staging (shadow) environment.

staging.ssh_port

–

Unique SSH port for the staging environment.

development.domains

wordpress.local

List of local domains routed to the local Nginx container.

development.pull_production_db

never

Determines whether the production database is pulled automatically on container startup (always or never).

development.pull_production_plugins

never

Determines whether production plugins are pulled automatically on container startup (always or never).

development.pull_production_themes

never

Determines whether production themes are pulled automatically on container startup (always or never).

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 up fails 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 beneath domains:.

  • A newly added domain in development.domains does not load in the browser: Saving config.yml alone does not update network routing for an already running container. Run seravo-docker down && seravo-docker up in your project directory, and verify that your local DNS resolver (dnsmasq) or hosts file resolves the .local domain to 127.0.0.1.

  • wp-pull-production-* commands fail to connect to the production server: Verify that the name field in config.yml matches your site's SSH username and that production.domain and production.ssh_port match your production environment details.

  • Local database changes disappear when restarting the container: Check config.yml to ensure pull_production_db is not set to always.

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

Did this answer your question?