Back to Notes
Fast and local development for Craft CMS using Docker
Blog post
Quickly get your Craft site running inside of Docker, without the performance hiccups.
## 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](https://ddev.readthedocs.io/en/latest/users/usage/architecture/).
## 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:
```php
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](https://ddev.readthedocs.io/en/stable/#installation).
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](https://github.com/onedarnleyroad/craftcms) to get it working 😇
If you're starting a new project with Composer:
```bash
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](https://ddev.readthedocs.io/en/latest) for the latest!