With Docker and DDEV-Local installed within our Linux distribution (Ubuntu), we are now going to create our first “DDEV container” (which is actually a docker container created via DDEV, but for now, you really mustn’t be too worried about that).
One important aspect to note here is that all the files we’re going to create and work with will and must be stored within the Linux distribution’s filesystem, or else it simply put means trouble.
However, thanks to the magic of WSL2, we can conveniently access and modify these files by using the following path in Windows Explorer (or any Win-based IDE, respectively):
The first DDEV container
1. Creating a new DDEV project
With Docker Desktop running, open up your Ubuntu Terminal (bash) and run the following commands:
cd mkdir your-project cd your-project ddev config
This creates a new folder named “your-project” inside your Ubuntu user’s home directory, then CDs into that folder and starts the DDEV configuration wizard.
In Windows, you can access this folder via the following path (with <user> being the name of your Ubuntu user):
2. Initial configuration
In the following steps, you’ll first get asked to choose a name for your new project. By default, this project name will make up the local URL of your project, i.e.:
Next, you’ll get asked for the docroot location. This is the folder the webserver’s going to route all requests from your project’s local URL to (https://your-project.ddev.site). With many frameworks (such as Zend, Laravel or Ruby on Rails), this is “public” by default, so for the sake of this tutorial, I’m going to go with that.
If you leave this blank, all server requests will be routed to the project root itself.
Lastly, you’ll get asked for the type of your project. Here you can choose between a couple of pre configured setups for various frameworks such as Drupal, Shopware, Typo3 or WordPress. For this tutorial, however, we’re going to keep it simple and stick with “php” (which gets chosen by default if you just leave this blank).
3. Adjusting the config
After running the configuration wizard, you’re going to find that – along with the empty docroot directory – a new folder called “.ddev” has been created inside your project folder. This folder contains your DDEV configuration files (of which, right now, there’s only one named “config.yaml”), as well as everything else DDEV-related.
Now, to get a feel for DDEV’s inner workings and adjust a few basic settings, let’s take a closer look at the “config.yaml” file. To do so, just run the following command via bash:
As you’ll see, the file itself is pretty well documented, but I’d still like to go over some basic settings you may want to adjust right away.
First off, if your project allows for it, I’d generally recommend going with the latest, stable version of PHP – so I’ll change that to “8.1” (please ignore the screenshots with 8.0, they are older than the stable release of 8.1 🙈).
Next up, if you aren’t as familiar with NGINX and/or would prefer running an Apache-Server, you may want to change the webserver_type to “apache-fpm”.
This setting determines whether Xdebug will be auto-enabled on startup of your container, which I’d generally recommend against – if only for the negative impact it’ll likely have on your system’s performance.
Instead, once DDEV is running, you can always start Xdebug manually by running the following bash command inside your project folder:
Then, once you’re finished debugging, you can turn it off again via:
ddev xdebug off
(This works for php CLI scripts as well!)
Should you plan on working on your DDEV project while being offline for whatever reason, you may want to set use_dns_when_possible to “false”.
This’ll make DDEV add an entry to your hosts file upon starting the project, which means you’ll be able to access it via its local URL (https://your-project.ddev.site) without any internet connection.
4. First DDEV start
After saving the changes we made to the config via CTRL + X (I feel you Windows brothers and sisters! ;D), it’s time to start our new DDEV project by running the following command:
On first startup, this’ll take a little while (especially because the docker images need to be downloaded), but after a couple of seconds you should find that DDEV has successfully started.
Now, in order to confirm everything’s working fine, I’d recommend first running the following command…
…which – aside from showing you each services status – also gives you a really nice overview of all URLs, IPs and access data involved with your project:
Next, we’re going to create a phpinfo-file inside our project’s docroot directory (“public”) by running the following command:
echo "<?php phpinfo();" >> public/index.php
With that, it’s time to put the system to the ultimate test by adressing the project’s local URL (https://your-project.ddev.site) inside your browser, or – if you’d like to go about this the “fancy way” – having DDEV do that for you by using one of its many more handy commands:
Et voilà – our first DDEV container all up and running, and as you can tell, our config changes have already taken effect, too. Hooray!
Other DDEV commands (Cheat-Sheet)
Now, before leaving you to take it from here, I’d like to give a brief overview of the most common commands you may want to run when working with your DDEV project(s) – just so you won’t have to look them up.
One important note, though: These’ll only work as long you’re inside the respective DDEV project’s folder (within bash).
1. Importing an SQL-dump
To import a (gzipped) SQL-dump, just run the following command (assuming the SQL-dump resides inside your project’s folder):
ddev import-db -f <dbdump>.sql.gz
2. Opening a session inside the DDEV container
To open a bash session inside the DDEV container, just run:
To logout again, you can use CTRL + D.
3. Stopping or restarting the DDEV container
To stop or restart the DDEV container (for example after making changes to the config), just run:
ddev stop or ddev restart
4. Deleting a DDEV project alltogether
Finally, if you’d like to delete a DDEV project, go ahead and stop the container, then run:
This creates a snapshot of the database and stores it within the “.ddev” folder (so you won’t have to back it up manually). Since the other contents of the “.ddev” folder will likewise remain untouched even after deletion, you can use this as a method for fixing a broken config, or to reset the container “the hard way”, so to speak.
However, should you really want to get rid of it altogether, just delete the project’s folder and it’ll be entirely gone at this point (with the exception of some cache-data).
And that’s about it! I hope you found this little tutorial to be useful, and if you have any questions, feedback or suggestions regarding it, please feel free to leave a comment below!