Writing
Blog post

Fast and local development for Craft CMS using Docker

August 16, 2023

What is DDEV?

DDEV is a tool that works with Docker to simplify setting up and managing your local dev environment. Explicit support for Craft CMS was added in October 2022, but it works with any PHP-based project.

Behind the scenes, DDEV uses docker-composer to define and manage your environment. The yaml files it creates are stored in a hidden .ddev folder, along with other configuration files.

How does DDEV work with Docker?

DDEV uses Docker to create isolated environments for your projects. Your web server is hosted in one container, and the database in another. Each website will have its own pair.

  • Web container: This container runs the web server (Apache or Nginx) and PHP.
  • Database container: This container runs the database server (MySQL or MariaDB).

Optionally, your project may optionally need one or more utility containers for additional services, such as:

  • PHPMyAdmin to manage your databases through a web interface
  • Redis for in-memory storage
  • MailHog for mail

Thanks to DDEV, getting these containers to talk to one another is easy. Docker provides built-in DNS resolution for container names within the same network, allowing containers to communicate with each other using their names instead of IP addresses or container IDs. This makes it feasible for DDEV to streamline a lot of the configuration. If you don't have a DevOps person on your team, this is almost as sweet!

For example, in a Craft CMS project, a common DB configuration in config/db.php would use something like this, with the container name "db" as the hostname:

return [
    'dsn' => getenv('DB_DSN') ?: 'mysql:host=db;dbname=my_database',
    'user' => getenv('DB_USER') ?: 'db_user',
    'password' => getenv('DB_PASSWORD') ?: 'db_password',
    'schema' => getenv('DB_SCHEMA') ?: 'public',
    'tablePrefix' => getenv('DB_TABLE_PREFIX') ?: '',
];

In the example above, the host db gets resolved to the database container through Docker's built-in DNS resolution system.

Can you retroactively use DDEV in an existing project?

Yes. This is what makes it so easy to get started!

Follow these steps:

  1. Install DDEV on your system.
  2. In the terminal, cd to your existing project's root directory.
  3. Run ddev config and follow the prompts to configure your project for DDEV.
  4. Run ddev start to launch your project's containers.

The magic happens in that third step, so if you run into problems, focus on your ddev config.

How do I get DDEV working with Vite?

Vite is useful for Hot Module Replacement (HMR) or bundling assets for deployment. The key to your configuration kingdom lies in using Vite's development server as a reverse proxy. To be honest, I used this boilerplate to get it working 馃槆

If you're starting a new project with Composer:

composer create-project onedarnleyroad/craftcms PATH --no-install

What is Mutagen and why does it speed things up?

I've noticed some of my Craft sites bog down inside of a Docker container. Mutagen is a file synchronization tool that improves the performance of file sharing between your host machine and Docker containers. At least on Mac, this can mean pretty significant gains in speed.

What are some handy commands?

Ready to get started? Here are a few helpful commands:

  • ddev start: Start your project's containers.
  • ddev stop: Stop your project's containers.
  • ddev restart: Restart your project's containers.
  • ddev ssh: Access the web container's command line.
  • ddev exec [command]: Run a command within the web container.
  • ddev import-db: Import a database dump into your project.
  • ddev export-db: Export your database.

Where do I start?

This post was published on 17 April 2023, so be sure to consult the DDEV docs for the latest!

Latest posts