If you’re a developer looking to elevate your WordPress projects, or if you’re exploring advanced, secure, and efficient ways to manage WordPress installations, you’ve come to the right place to learn about Bedrock and DDEV.

In this tutorial, I will guide you from start to finish on setting up a local WordPress development environment using DDEV, running Bedrock—a WordPress boilerplate that improves security, dependency management, and environment configuration—and preparing everything for a smooth transition to production.

Bedrock restructures WordPress for better security and easier management, using environment-specific configuration files and Composer for dependency management. DDEV provides a powerful and flexible local development environment that supports multiple PHP applications, simplifying the process with containerization technology.

By the end of this tutorial, you will have a fully functioning WordPress setup that is more secure, easier to manage, and ready to scale. This setup not only meets the demands of modern web development practices but also optimizes your development workflow, allowing you to focus more on development and less on configuration.

Whether you are looking to streamline your development process, implement industry-standard tools, or simply want to learn about advanced WordPress setup, this tutorial will provide you with the knowledge and tools to get there.

Summary

Step 1: Understanding Bedrock and DDEV

In this tutorial, I’m going to explore two powerful tools that dramatically transform the WordPress development landscape: DDEV and Bedrock.

Bedrock restructures the standard WordPress setup into a more manageable and secure configuration. It integrates Composer for dependency management, allowing you to handle plugins and themes as packages. This not only makes your site more secure and easy to maintain but also ensures it is version-controlled, laying a solid foundation for building robust WordPress applications.

DDEV uses Docker to create isolated environments, known as containers, for each project. This is particularly beneficial when developing with Bedrock, as each WordPress project can have its own specific versions of PHP, web server settings, and other server-side services without affecting other projects on the same machine.

Together, DDEV and Bedrock streamline the workflow for developing, testing, and deploying WordPress sites with enhanced security and efficiency.

Docker is an open-source platform that uses containerization technology to make it easier to create, deploy, and run applications by using containers. Containers allow a developer to package up an application with all the parts it needs, such as libraries and other dependencies, and ship it all out as one package. By doing so, one can be assured that the application will run on any Linux machine, regardless of customized settings. This assurance extends to machines with configurations that differ from those used during the writing and testing of the code. The application will also run on macOS and Windows machines.

Each project is managed within its own isolated environment in DDEV, which comprises multiple Docker containers. Each container serves a different function—one might handle the web server, another the database, and so on. Conceptually, you can think of it as ‘one container per project’ because all these containers work together seamlessly to support a single project.

Docker guarantees that a development environment is consistent with a production environment. Since Bedrock relies on specific server configurations and Composer for dependency management, Docker ensures that one can replicate these environments accurately across different development stages and team members’ machines.

Thanks to Docker, DDEV allows you to easily start, stop, or restart services without affecting the underlying host system. This flexibility is invaluable when testing different configurations or updates, as it fits perfectly with Bedrock’s structured and modern approach to WordPress development.

As projects grow, Docker makes it easy to scale applications by increasing container replicas or distributing them across multiple machines. This is particularly useful for large-scale WordPress sites developed with Bedrock, providing an efficient way to handle traffic spikes and load balancing.

The Basics: Some Key Terms

Here are some definitions for other key terms. We’ve already discussed Docker extensively in the introduction, so we won’t be revisiting it here. Instead, let’s focus on other essential concepts like modern workflow, the 12-factor app methodology, and DDEV—all in the context of using Bedrock for WordPress development.

A modern workflow in web development refers to practices that make building, testing, and deploying applications more efficient and less prone to errors. This includes using version control, staging environments, continuous integration, and deployment automation. With Bedrock, the modern workflow is embodied through the use of Composer for dependency management, environment-specific configurations, and seamless integration with advanced development tools like DDEV, which provide isolated environments and support continuous development without disruptions.

The 12-factor app is a methodology for building software-as-a-service apps that emphasizes portability, resilience, and scalability. Applying the 12-factor principles to WordPress development with Bedrock involves using environment variables for configuration (avoiding hard-coding configurations into the code), strict separation of build and run stages, and treating logs as event streams. Bedrock is designed to be 12-factor compliant in many ways, which makes it robust for cloud environments and scalable deployments.

DDEV is an open-source tool that simplifies the complexities of setting up and managing local development environments across multiple projects. It uses Docker to provide isolated, Docker-based environments tailored for web development. Within Bedrock, DDEV ensures that each WordPress setup has its own unique environment without the risk of interfering with other projects on the same system. This isolation helps maintain consistency between development, staging, and production environments, making DDEV an integral part of a modern development workflow with Bedrock.

Step 2: Essential Tools and Prerequisites for Bedrock and DDEV

Before we start setting up our WordPress environment with Bedrock and DDEV, it’s important to ensure you have the correct setup and understanding of the tools we will be using. This section covers what you need to get started.

Docker Installation

DDEV runs on Docker, so you must have Docker installed on your computer. Docker allows us to create isolated development environments through containers. You can download it from the Docker website.

For Windows and macOS users, it is recommended to install Docker Desktop. Docker Desktop provides a GUI and includes a lot of extra Docker-related services. It simplifies Docker management and is suitable for development. You can download Docker Desktop from the Docker website.

For those in development or test environments in Linux, using Docker’s convenience script can be an effective way to install Docker. The convenience script is provided by Docker to streamline the installation process on Linux. This script automates several steps involved in the installation and can be a quicker setup method for developers who frequently need to install Docker on various systems.

Please, keep in mind that while this script simplifies the process, it’s always a good practice to review scripts before running them, especially with sudo privileges. For production environments, it’s advisable to follow the more detailed installation instructions provided on Docker’s official installation guide to tailor the setup to your specific needs and ensure security measures are in place.

You will use DDEV to manage these Docker containers and simplify your WordPress development workflow. DDEV includes tools like Git and Composer within its containers, making it easier to manage your project dependencies and version control.

DDEV Installation

DDEV can be installed in various ways depending on your operating system:

  • For macOS and Windows, using Homebrew (macOS) or Chocolatey (Windows) is recommended:
    • macOS: Run brew install drud/ddev/ddev in your terminal.
    • Windows: Run choco install ddev in your command prompt as an administrator.
  • For Linux, you can install DDEV using the script provided in the installation guide, or use Linuxbrew if you prefer.

After installation, you can verify that DDEV is correctly installed by running ddev version in your terminal. This command will display the version of DDEV installed and confirm it is ready to use.

DDEV requires Docker to be running in the background to manage and utilize Docker containers.

This is a common setup error where users install DDEV but forget to start Docker before using DDEV commands. If Docker is not running, DDEV will not be able to create or manage Docker containers, leading to errors. If you encounter an error stating that DDEV cannot connect to Docker, first ensure that Docker is running. Restarting Docker can also resolve issues where Docker services haven’t initialized properly after booting your computer.

How to Ensure Docker is Running:

  • Windows/MacOS: You can start Docker Desktop by searching for it in your applications and clicking to open it. Ensure it shows ‘Docker is running’ in the taskbar icon or dashboard.
  • Linux: Depending on your Docker installation, Docker usually runs automatically after installation. You can check if Docker is active by using sudo systemctl status docker in your terminal. If it’s not running, you can start it with sudo systemctl start docker.

While systemctlis part of the systemd system and service manager used by many modern Linux distributions, including popular ones like Ubuntu, Debian, Fedora, and CentOS, there are distributions that do not use systemd. For example, distributions like Gentoo, Alpine Linux, and some versions of Slackware use other init systems. In those cases, the process to manage Docker or any other service might differ. For instance, Alpine Linux (a common distribution used inside Docker containers often, so it’s worth mentioning) uses OpenRC, and the commands to check service status or start services would look different, such as:

rc-service docker status
rc-service docker start

Working “inside the container”

When setting up your WordPress environment with Bedrock and DDEV, you have the flexibility to manage dependencies and version control either through tools installed on your host system or directly within the DDEV containers. DDEV containers come pre-equipped with both Git and Composer, simplifying the setup and usage.

Understanding what it means to use these tools “inside the container” and the differences between using them inside versus on the host is very important for your workflow.

Running tools “inside the container” means executing commands in an isolated environment that DDEV creates using Docker. Each container has its own copies of software tools, like Composer and Git, and its file system separated from your host machine. This setup ensures that operations performed inside the container are consistent across all development environments and are not influenced by variations in developer’s local setups.

Executing tools “inside the container” involves interacting with a software environment that is encapsulated within a Docker container managed by DDEV. This container acts similarly to a virtual machine, but is more lightweight and integrated directly with the host machine’s Docker engine.

The first step to running tools inside the container is to access the container’s command line interface. You do this using the command ddev ssh. This command connects you to a shell session inside the Docker container where your project is running. Executing ddev ssh effectively “teleports” you into the isolated environment of your project, separate from your local machine’s environment.

Once inside the container, you are working within a controlled setup that DDEV configures based on the specifications of your project. This setup includes pre-installed tools like Composer and Git. The container includes its own software versions and configurations. These are consistent regardless of what machine the container is running on, which helps in maintaining consistency across different development setups.

When you run Composer commands inside the container (after you’ve accessed it via ddev ssh), you are using the version of Composer that comes pre-packaged with DDEV. This ensures that all dependencies managed by Composer are compatible with the container’s environment.

For example, if you need to add a new plugin to your WordPress site, you would run a command like composer require wpackagist-plugin/slug-of-the-plugin inside the container. This command uses the container’s Composer, ensuring that all team members are adding plugins or updating dependencies under the same environment conditions.

Since everyone on your team accesses the same containerized environment thanks to DDEV, it reduces the “works on my machine” problems that often occur when different team members have different configurations. Changes made inside the container do not affect the host machine. This isolation protects your host system from potential issues arising from development work, such as conflicting software versions or configuration discrepancies.

When you’re finished running commands inside the container, you can exit the session by typing exit. This command logs you out of the container’s shell and returns you to your local machine’s command line interface, where you can continue other tasks not related to the containerized environment.

Step 3: Choosing Your Composer Setup in DDEV

Choosing the right Composer setup in your DDEV environment is key to adapt your WordPress development projects. We are going to explore three different configurations for using Composer with DDEV—each with its own set of advantages and disadvantages.

ConfigurationAdvantagesDisadvantages
Using only Composer in DDEVEnsures consistency across all environments as every developer uses the same version of Composer regardless of what’s on their local machine.
Reduces setup complexity since there’s no need to install Composer on each developer’s computer.
Developers must use DDEV commands to interact with Composer, which may involve a learning curve or slight adjustments in workflows, especially when someone in the team does not work with DDEV.
It might also limit executing Composer commands when outside of the DDEV environment.
Using Composer Inside DDEV and on the HostOffers flexibility—developers can run Composer commands directly on their host for quick changes or within DDEV for full compatibility with the project’s environment.
It allows for easier integration with other tools and IDEs on the host system.
Developers must use DDEV commands to interact with Composer, which may involve a learning curve or slight adjustments in workflows, especially when someone in the team does not work with DDEV.
It might also limit executing Composer commands when outside of the DDEV environment.
Ignoring the Composer in DDEV and Using Only the Host’s InstallationKeeps the development environment aligned closely with the developer’s usual tools and setups, potentially speeding up the development process for those accustomed to their configured environments.Increases the risk of environmental discrepancies between development and production. Requires all developers to maintain their Composer installations and manage potential conflicts between local and container environments.

If after reading the comparison you want to proceed having composer in the host machine rather than only inside the container, here is some help. Let’s start with instructions for macOS and Linux:

Open your terminal and execute the following command:

curl -sS https://getcomposer.org/installer | php

This command downloads the composer.phar file, which is the Composer binary. This file is executable and can be used directly to manage dependencies.

You might want to move the Composer binary to a directory in your PATH for ease of use. Run:

sudo mv composer.phar /usr/local/bin/compose

This command moves the Composer binary to /usr/local/bin, making it executable from any directory by simply typing composer.

If you are in Windows, visit the Composer Download page. After that, follow the instructions there. It will guide you through setting up Composer on your Windows system, including adding it to your PATH, so it’s accessible from any command prompt. To confirm that Composer has been installed correctly, open your command prompt and type: composer. This command should display the Composer version along with a list of commands available in Composer.

Git Set Up

As for Git, many developers have their Git configurations and credentials finely tuned on their host machines. This includes global Git settings, SSH keys for repository access, and user configurations that are not automatically shared with the container environment. Using the host-installed Git allows developers to leverage these pre-configured settings seamlessly.

Developers often use GUI-based Git tools or integrated development environments (IDEs) that integrate directly with the Git installation on their host machine. These tools may provide more sophisticated interfaces for managing commits, branches, and merges than command-line tools available within a container. Using the host’s Git installation ensures a smooth integration with these tools. 

For some workflows, especially in a development environment where frequent commits are made, having to ddev ssh into a container to perform Git operations can add unnecessary complexity and steps. Using the host’s Git installation simplifies the workflow, allowing for quick changes without the need to switch contexts. But other than these reasons, nothing prevents you from using the git that is inside the container. It just can be a bit more uncomfortable sometimes.

Step 4: Scaffolding a WordPress Development Environment with Bedrock and DDEV

To begin setting up our WordPress environment with Bedrock and DDEV, we need to start by creating a project directory and a DDEV configuration file within it. This configuration file, named .ddev/config.yaml, tells DDEV how to set up the development environment.

Create a project directory

The project directory will serve as the root for all our project files and configurations. There are several ways you can create this directory, depending on your preferred tools.

If you are comfortable using a command line interface, you can quickly create a project directory by following these steps:

  1. Open your terminal.
  2. Run the following commands:mkdir <YOUR_PROJECT_NAME>
    cd <YOUR_PROJECT_NAME>

Replace <YOUR_PROJECT_NAME> with the actual name of your project. This creates a new directory and then changes the current directory to your new project directory.

You can also create a project directory manually using your system’s file explorer.

No matter which method you choose, having a project directory is the first step because it organizes your project’s assets and configurations in one place. This directory is also where you’ll create the .ddev/config.yaml file, which is essential for setting up and managing your DDEV environment tailored to your WordPress project using Bedrock.

By making sure that you set up the directory from the beginning, you create a structured environment that supports the complexities of modern web development, facilitating better management and the scalability of your project.

Populating the directory

Continuing with the setup of your WordPress environment using Bedrock and DDEV, the next step is to create a .ddev/config.yaml file within your project directory. This file plays a very important role in configuring your development environment settings tailored specifically to your project needs.

In Unix-like operating systems, such as Linux and macOS, files and directories that start with a dot (.) are considered hidden. This naming convention is used to reduce clutter in directory listings and to keep configuration files from being altered unintentionally.

In the terminal, files or directories that begin with a dot do not appear in the standard directory listing produced by the ls command. To view these hidden files, you can use the command ls -a, where the -a option stands for “all”, indicating that you want to list all files, including hidden ones.

In macOS, by default, Finder does not show hidden files. To toggle the visibility of hidden files, you can use the shortcut Cmd + Shift + .. When in GNU/Linux, in GNOME, you can press Ctrl + H to toggle the visibility of hidden files. In KDE Dolphin, you can similarly use Alt + . to show or hide hidden files.

As for Windows, since it’s not a UNIX-like operating system, command line tools like Command Prompt or PowerShell do not hide dot files by default. They are visible unless the folder options or specific application settings hide them. Windows File Explorer does not hide files starting with a dot by default either. However, you can set File Explorer to hide or show hidden files (including system files that start with a dot) through the View tab. Click on “Options”, then change to the “View” tab in the Folder Options dialog box, and check or uncheck “Hidden items” as needed.

Creating a directory like .ddev follows this convention, indicating that it’s typically used for configuration or operational purposes that regular users do not need to interact with daily. By using a dot prefix, we keep the directory semi-hidden, reducing clutter and minimizing the risk of accidental modifications.

Your DDEV directory

The .ddev directory must be placed as a direct subdirectory of your project directory. Here is what your basic .ddev/config.yaml should contain:

name: <NAME OF THE PROJECT>
type: wordpress
docroot: web
php_version: "8.2"
webserver_type: nginx-fpm
database:
type: mariadb
version: "10.3"
xdebug_enabled: false

Let’s explore these tags and explain what they mean:

name

This is your project’s name. Replace <NAME OF THE PROJECT> with the actual name you wish to give your project. This name is used by DDEV to identify your project uniquely among other projects you might be running simultaneously.

type

This specifies the type of project. For this tutorial, we’re using WordPress, so it’s set as wordpress.

docroot

This specifies the root directory of your web server. For Bedrock projects, this is typically web, which is the directory that Bedrock uses to serve WordPress files. The docroot setting in a Bedrock project represents a key difference from the traditional file structure used by vanilla WordPress installations. In a standard WordPress setup, the root directory (where WordPress is installed) contains all the core files, plugins, themes, uploads, and WordPress configuration files such as wp-config.php. This layout is not only visible by default on the web, but also mixes sensitive configuration files and publicly accessible assets, which can raise security concerns. 

In traditional WordPress, the WordPress root directory (/) serves as both the web root and the location for all core files, plugins, themes, and configurations, and wp-config.php, the main configuration file, resides in the root directory, making it more exposed to web access. All core WordPress files are in the root directory, along with media uploads and plugins, making the entire structure somewhat cluttered and less manageable in terms of access control and security. 

In Bedrock, in contrast, the document root is set to web, which is a subdirectory within the Bedrock project structure. This directory becomes the web root, meaning it is the only part of the structure exposed to the web. Critical configuration files, including environment-specific settings, are kept outside the web directory, enhancing security by reducing direct web access to sensitive files: Bedrock segregates WordPress core files into a subdirectory within web (typically web/wp), separating them from user content, plugins, and themes.

By storing configuration files and other sensitive data outside the web-accessible directory, Bedrock minimizes the risk of exposure to potential security threats. This layout makes it harder for attackers to access critical files via URL guessing or direct web access. Security is further bolstered by the use of environment variables and an .env file for managing sensitive data like database credentials and security keys, rather than storing them in wp-config.php.

php_version

Indicates the PHP version your project requires. We’re using PHP 8.2 here. This makes it straightforward to align your development environment with the production environment or any other specific setup that requires a particular PHP version. One of the common challenges in web development is ensuring that your application runs smoothly across different PHP versions, especially when new versions are released or when preparing to upgrade the PHP version on production servers. 

DDEV addresses this challenge by allowing you to change the PHP version in a single configuration line and then simply restarting the environment. Simply changing the php_version in .ddev/config.yaml, you can test how your site behaves under different PHP versions. This is very useful for checking compatibility with new PHP releases or ensuring that updates to your site do not introduce issues in older versions still in use. After updating the PHP version in the configuration file, running ddev restart applies the changes. 

DDEV handles the underlying tasks of pulling the appropriate Docker images for the specified PHP version and reconfiguring the containers to use this new setup. This process is quick and does not require manual reconfiguration of the server or containers.

webserver_type

Specifies the type of web server DDEV should configure. We’re using nginx-fpm because it’s well-suited for modern PHP applications.

database

Defines the type and version of the database. Here, we’re using MariaDB version 10.3.

xdebug_enabled

Determines whether Xdebug is enabled for debugging. Here, it is set to false to disable it by default, which you can enable as needed.

Xdebug is a powerful tool primarily used for debugging PHP code. It provides developers with a way to step through their code, analyze variable values, and track the execution of scripts in real time. Xdebug integrates with various Integrated Development Environments (IDEs) to enhance the debugging process, making it easier to identify and resolve issues within your code.

It also allows you to stop the execution of PHP code at any point and inspecting the state of the application, similar to debugging in other programming languages, as well as enhancing error messages with detailed information on what functions were called, from where, with what parameters, and the file and line numbers involved.

We have set the xdebug_enabled option to false in the .ddev/config.yaml file. This is to ensure that Xdebug does not interfere with the basic setup and operations of your WordPress site using Bedrock and DDEV. It’s typically activated only when needed for specific debugging tasks for performance reasons.While this tutorial does not look into configuring and using Xdebug with your IDE, it’s important to know that this tool is available and can be enabled if you encounter complex issues that require detailed debugging. If you choose to enable Xdebug later, you can simply change the xdebug_enabled setting from false to true in your .ddev/config.yaml file, and restart your DDEV environment by using ddev restart.

Step 5: Launching Your WordPress Development Environment

After setting up your project directory and configuring the .ddev/config.yaml file, the next step is to initialize your local development environment using DDEV. This process is executed from the command line interface (CLI), which allows for direct interaction with DDEV’s powerful suite of tools. To start, you’ll need to open your terminal (or Command Prompt in Windows) and navigate to your project directory.

Running this command brings your development environment to life, making it operational for development tasks.

Launch with ddev start

When you execute ddev start in your terminal within the project directory, several actions take place. Most important one is that DDEV utilizes the settings defined in your config.yaml file to start up Docker containers. Each container is a separate environment configured specifically for aspects of your WordPress setup—such as the web server, PHP processor, and database.

DDEV checks the environment to ensure all dependencies and configurations are correct. If any settings need adjustment or if additional components need to be downloaded, DDEV handles this automatically. It also configures a local network for your containers, allowing all containers to communicate with each other. 

This network mimics a real-world server setup, providing an accurate development environment that closely mirrors production.

Upon successful start, DDEV provides you with URLs to access your local development site. Typically, these URLs are based on the project name and end with .ddev.site, like http://yourprojectname.ddev.site. This URL can be used in your browser to view and interact with your WordPress site as you develop.

With the environment running, tools such as Composer, npm, and others that you’ve configured in DDEV are now accessible. You can run commands specific to these tools directly in the container’s command-line interface, ensuring that all team members are working under identical conditions.

Operational files

When you run ddev start, the .ddev directory is populated with various operational files and configurations that extend beyond the initial config.yaml. This includes:

  • Dynamic Configuration Files: These files are automatically generated and updated by DDEV based on your project’s ongoing needs and settings adjustments. They are there for tailoring the development environment to specific requirements.
  • CA Certificates and Logs: Needed for managing secure connections and debugging processes, respectively.

To maintain a clean repository and ensure that temporary or environment-specific files do not clutter your project’s version control, DDEV automatically configures a .gitignore file within the .ddev directory. This file specifies patterns for excluding certain files and directories from Git tracking, such as:

  • Temporary data
  • Local configuration overrides
  • Logs

This exclusion helps keep your Git repository focused on source code and vital configurations, avoiding unnecessary data that could complicate project management or inadvertently expose sensitive information.

Step 6: Installing Up Bedrock in Your Brand New Local DDEV Environment

The following process will ensure that Bedrock is installed correctly within the Docker container provided by DDEV, using the pre-configured tools and settings for a streamlined setup. 

First, you need to access the command-line interface within your DDEV container where the project’s environment is configured. This is where you will run the commands to install Bedrock. Open your terminal and navigate to your project directory, then enter:

ddev ssh

This command connects you to a shell session inside the Docker container of your project. It “teleports” you into the isolated environment (you can think of it as a virtual machine, or a different machine inside your machine) where you can operate with tools and configurations specifically tailored for your project setup.

Once inside the container, you need to download and install Bedrock. I can’t assume everyone has the necessary tools installed on their host machine. So performing these steps inside the container ensures compatibility and access to required tools, because since DDEV is in place, everybody has the same tools inside the container.

git clone https://github.com/roots/bedrock.git temp_bedrock

This command clones the Bedrock repository into a directory named temp_bedrock. We use a temporary directory to handle the extra level of directory structure that Git creates.

Once you have cloned Bedrock into the temporary directory within the container, exit the container environment to handle file operations from your host machine. You can do this by typing exit in the terminal. To organize the project correctly, you need to move the contents of temp_bedrock up one directory level into the main project directory. Execute these commands:

rm -rf web/
cp -R temp_bedrock/* ./
rm -rf temp_bedrock

These commands ensure that all files, including hidden ones that start with a dot (like .env or .gitignore), are moved correctly. Then run ddev start again to jump to your container.

After moving all the files, the temp_bedrock directory will be empty. You can safely remove it with:

rmdir temp_bedrock

Step 7: Understanding the Environment: Essential .env Settings for Effective WordPress Development

Now that Bedrock is successfully installed in your DDEV environment, let’s proceed tinkering with the .env file. This file determines how Bedrock manages environment-specific configurations, which are needed for both development and production environments.

First, if you are still inside the DDEV container, you need to exit to your host environment where you can comfortably edit the .env file using your preferred text editor or Integrated Development Environment (IDE). Simply type exit. This command will bring you back to your project directory on your host machine in your command line.

When you use Git to clone the Bedrock repository, it includes a .env.example file which is the way we downloaded Bedrock before, which serves as a template for setting up your own .env file. This template includes default settings that you can customize to fit your project’s specific needs.

First, ensure you are in the root of your project directory where you cloned Bedrock. Here you should find the .env.example file. Before you edit the settings, you need to copy or rename .env.example to .env. This can be done via the command line with the following command: cp .env.example .env. Now that you have your own .env file, open it with a text editor or IDE of your choice. If you are comfortable using the terminal, you can use editors like nano or vim. For a graphical interface, PHPStorm, Visual Studio Code, or any other code editor will work well. Edit the .env file to set the environment variables according to your project’s requirements and the standard DDEV database credentials (I will be explaining these in a moment).

.env files are simple text files that allow you to set environment variables specific to your project’s environment. These variables can drastically alter how your application behaves, making it easy to switch settings between development, staging, and production environments without altering code.

.env files

The .env file in Bedrock is similar to the wp-config.php in traditional WordPress setups but provides a more secure and flexible way to handle configurations. By separating environment-specific configurations from code (wp-config.php often ends up in version control, which is not ideal for security), .env ensures that sensitive information like database credentials and security salts are kept out of version-controlled files.

Here’s a breakdown of the essential .env variables you’ll need to configure, as outlined in the Bedrock documentation:

  • DB_NAME – The name of the WordPress database (e.g., wordpress)
  • DB_USER – The username for accessing the database
  • DB_PASSWORD – The password for the database user
  • DB_HOST – The hostname of your database server, typically localhost in development environments
  • WP_ENV – The environment type for your project (development, staging, production)
  • WP_HOME – The full URL to your WordPress site (e.g., https://yourproject.ddev.site)
  • WP_SITEURL – The full URL to the WordPress installation directory (e.g., https://yourproject.ddev.site/wp)
  • AUTH_KEY, SECURE_AUTH_KEY, LOGGED_IN_KEY, NONCE_KEY, AUTH_SALT, SECURE_AUTH_SALT, LOGGED_IN_SALT, NONCE_SALT – Unique phrases that enhance the security of your site. You can generate these using the WordPress Salt Generator.

Database credentials

When working within a DDEV environment, the default database credentials are standardized for simplicity. This setup helps streamline development by providing a consistent and predictable environment, reducing the need to customize database credentials for local development. Here’s what the typical database credentials look like in a DDEV setup:

  • Database name (DB_NAME): db
  • Database user (DB_USER): db
  • Database password (DB_PASSWORD): db
  • Database host (DB_HOST): db

Note that DB_HOST in the default .env.example is commented out. Remove the # to uncomment it. Here is how you would set these values in your .env file for a Bedrock project running under DDEV:

DB_NAME='db'
DB_USER='db'
DB_PASSWORD='db'
DB_HOST='db'
WP_ENV='development'
WP_HOME='http://yourprojectname.ddev.site'
WP_SITEURL="${WP_HOME}/wp"
# Security keys can be generated using the WordPress Salt Generator
AUTH_KEY='put your unique phrase here'
SECURE_AUTH_KEY='put your unique phrase here'
LOGGED_IN_KEY='put your unique phrase here'
NONCE_KEY='put your unique phrase here'
AUTH_SALT='put your unique phrase here'
SECURE_AUTH_SALT='put your unique phrase here'
LOGGED_IN_SALT='put your unique phrase here'
NONCE_SALT='put your unique phrase here'

Using these standard credentials simplifies the initial setup and allows you to focus more on development rather than configuration.

It’s important to note that these credentials are intended for local development only. For staging or production environments, you will need to use different, secure credentials appropriate for those environments.

Step 8: Composer install

After moving the Bedrock files into your project directory, you might encounter an error indicating that WordPress core files are missing if you navigate to your project’s URL. This is a common issue and signals that the necessary PHP dependencies, including the WordPress core, have not been installed. To address this, you need to run Composer within the DDEV container.

Before running Composer, you must access the container’s command-line interface where your project is set up. If you are not already inside your DDEV container, navigate to your project directory in the terminal and type:

ddev ssh

Inside the container, run Composer to install the necessary dependencies. Make sure you’re in your project’s root directory where the composer.json file resides and execute:

composer install

This command will download and install the WordPress core and other required PHP packages as defined in your composer.json file.

Your DDEV information

After the installation process is complete, you can exit the container by typing exit. Then, use the following DDEV command to ensure your environment is correctly set up and running:

ddev describe

With the .env file properly configured, and composer install ran, your Bedrock installation should now be fully functional within your DDEV environment. This configuration ensures that Bedrock can connect to the database using the DDEV-provided credentials and operate based on the environment settings you specified.

To access and set up your WordPress site, you can use the ddev describe command. This command provides details about your environment, including URLs to access your project.

The output will include a URL under the http and https URLs section that looks something like http://yourprojectname.ddev.site. This URL is where your Bedrock-based WordPress site is accessible. Opening this URL in a web browser will direct you to the WordPress installation process, where you can configure your site’s title, admin username, password, and email.

The ddev describe command is very helpful as it not only shows URLs for accessing your project but also displays database credentials, PHP version, and links to other services like MailHog for email testing. Here’s a breakdown of some typical outputs from ddev describe:

  • Project name: Indicates the name of the project as specified in .ddev/config.yaml.
  • PHP version: Shows the PHP version configured for use in the project.
  • MySQL/MariaDB credentials: These are standard across DDEV environments unless changed. It generally includes DB_NAME, DB_USER, DB_PASSWORD, and DB_HOST, all set to ‘db’.
  • MailHog URL: Provides a link to access MailHog, a tool for testing email functionality without sending real emails.
  • phpMyAdmin URL: Provides a link to phpMyAdmin for managing the database through a web interface.

These tools and configurations help ensure that your development environment is as close to your production environment as possible, providing consistency across different stages of development.

Step 9: How to Import Database Dumps Effectively in Your Local DDEV Setup

Sometimes the purpose of setting up a new WordPress project locally, whether using Bedrock or a vanilla installation, is not to start from scratch but rather to replicate an existing online project. In these cases, you might already have a database dump, possibly compressed, that you need to import into your local development environment. DDEV makes this process straightforward and efficient, even allowing you to handle compressed database dumps directly.

How to import a database

DDEV provides a simple command to import databases directly into the container’s database service, which supports various formats, including raw SQL files and compressed files (.tar.gz, .zip, etc.) without any need to unarchive them first.

First, ensure your database dump file is in the project directory or a subdirectory that you can easily access from the DDEV command line.

Open your terminal and navigate to your project directory where the DDEV environment is initialized.If your database file is compressed (e.g., .tar.gz or .zip), DDEV can handle decompression automatically. Use the following command to import it:

ddev import-db --src=path/to/your/dumpfile.sql.gz

For an SQL file, the command is straightforward:

ddev import-db --src=path/to/your/dumpfile.sql

Here, --src flags the path to your source dump file. Adjust the path to where you’ve stored your dump file within your project directory.

Remember to work outside the container

One common mistake is attempting to run the ddev import-db command while inside the DDEV container. It’s important to remember that DDEV commands should be run from your host machine’s terminal, not from within the DDEV container. If you have accessed your container using ddev ssh, you will be in the shell environment inside the Docker container. To check, you can look at your terminal prompt. DDEV usually alters the prompt to indicate you are inside the container. It might include the project name or the word “web” indicating you are within the web service container.

If you find yourself inside the container, type exit and press Enter. This command will bring you back to your host machine’s terminal. Once you are back on your host, your terminal prompt should return to its normal state.

Changing your project’s variables

When you import a database from another environment or set up a Bedrock project locally, ensure that your .env file reflects the correct settings for WP_HOME and WP_SITEURL. Adjust these values according to your local development URL provided by DDEV. This approach means that any time you need to change the environment or move your site, updating these variables will suffice, without the need for additional steps or database manipulations.

Bedrock simplifies the management of environment-specific configurations through the use of environment variables, which is a significant advantage over traditional WordPress setups. This approach is particularly beneficial when changing the site’s URL, a common requirement when moving a site between environments (such as from production to a local development setup).

In traditional WordPress setups, changing the site URL typically involves updating entries in the database, either through the WordPress admin panel or by using WP-CLI commands to directly modify options like home and siteurl, and often even perform a serialized search and replace. This process can be cumbersome and prone to errors, especially when dealing with serialized data in the database.

Bedrock, however, uses environment variables set in the .env file to manage these settings, making the process more streamlined and error-free. Bedrock defines the WP_HOME and WP_SITEURL settings directly in the .env file. By setting these variables, you dynamically define the base URLs for your site without the need to alter database values. For example:

WP_HOME='http://yourprojectname.ddev.site'
WP_SITEURL="${WP_HOME}/wp"

In this configuration:

  • WP_HOME is the main URL of your WordPress site.
  • WP_SITEURL is the URL where your WordPress core files reside, typically extending WP_HOME with /wp when using Bedrock.

Using Bedrock’s environment variables for URL settings offers several advantages over the traditional WordPress approach. There is no need to perform database queries or use tools to serialize and replace URLs within the database. You simply update your .env file with the appropriate environment variables.

This method ensures also consistency across different environments (development, staging, production) by allowing you to set different .env files for each environment without modifying the database. Since the environment-specific settings are managed through the .env file, it’s easier to migrate the site across environments. You can have different .env configurations for each environment, which simplifies the setup process and reduces the chances of errors.

Exporting a database

After making changes or updates in your local development environment, you might want to export your database to replicate these changes in other environments, such as staging or production, or simply to keep a backup. DDEV also simplifies this process with its built-in commands for exporting databases directly from your container.

Export the database using the DDEV command. This command creates a dump of the database and can also compress the file if desired:

ddev export-db --file=path/to/your/outputfile.sql.gz

In this command:

  • --file specifies the path and filename for the output file. If you include a .gz extension, DDEV will automatically compress the file using gzip. If you prefer another compression format, like zip, you can manually compress the file afterward or specify the format if supported by DDEV.

You can also export the database without compression:

ddev export-db --file=path/to/your/outputfile.sql

If you simply run ddev export-db without any parameter, DDEV will create a unique filename for your export.

Step 10: Optimizing and Expanding Your WordPress Development Setup

You did it! You have successfully set up your WordPress environment with Bedrock and DDEV! 

By integrating these tools, you can benefit from a more structured, secure, and efficient workflow, which aligns with modern web development practices. As you incorporate these tools into your WordPress projects, you’ll likely see a decrease in setup and troubleshooting time, allowing for a smoother, more predictable development process.

Now that you have a solid foundation, it’s time to make the most out of your setup to push your development capabilities further.

Enhance Your Setup

First and foremost, it is a good practice to keep your WordPress, plugins, and themes up to date using Composer within your DDEV container. Regular updates help secure your setup against vulnerabilities and ensure compatibility with the latest web technologies. 

Moving further, you can utilize the flexibility of Bedrock to tailor your WordPress setup to your specific needs. Explore advanced plugins and themes that can enhance your site’s functionality and user experience. You can also implement caching solutions and performance optimization tools within DDEV to make your WordPress site faster and more responsive. Tools such as Redis or Varnish can be integrated into your DDEV setup to improve loading times and overall performance.

DDEV’s integration capabilities can help you automate your processes, such as testing and deployment, to simplify your development workflow and reduce potential errors that are to be expected when doing these operations manually. As your project grows, you can use DDEV to clone environments for team members, ensuring everyone works in a consistent development environment. This scalability is key for larger projects, and really helpful if you are thinking of expanding your development team.

Need Professional Help?

While this tutorial has equipped you with the knowledge to manage your WordPress projects independently, sometimes you might encounter complex challenges or require specific optimizations. If you find yourself needing expert advice or hands-on assistance to make the most out of your Bedrock and DDEV setup, visit My Expert Services. Whether it’s troubleshooting, performance optimization, or custom development, I’m here to help ensure your WordPress site performs at its best.