Kirby meets DDEV

DDEV is an increasingly popular Docker-based development tool that allows you to quickly set up and manage local development environments for different projects on Linux, Mac, or Windows.

So basically, it provides a Docker environment without you having to know anything about using Docker, unless you want to configure your own services.

Requirements

DDEV uses Docker to create and manage local development environments, therefore you need Docker installed on your computer. If you don't have Docker yet, head over to the DDEV website, where you can find installation instructions for different Docker providers recommended for your operating system.
You can use an existing project, or download/clone a Kirby Starterkit. We will also show how to install the Starterkit via DDEV.
Make sure you don't have any other services running on port 80, so stop your current webserver if its using this port.

Once Docker is installed on your system, you are ready to install DDEV. There are different ways to do this depending on your operating system. DDEV provides detailed installation instructions for each operating system. Simply follow these instructions and then head back here.

Once DDEV is installed and running, setting up a project is done with a few quick steps.

TL;DR

Clone or download the code for your project.
cd into the project directory and run ddev config to initialize a DDEV project.
Run ddev start to spin up the project.
Run ddev launch to open your project in a browser.

But let's go through these general steps in a little more detail and see how we can customize them for our needs.

Different use cases

If you already have a existing Kirby project (Starterkit or your own project), you can use that. Note that if you have a public folder setup, the configuration is a bit different, see Public folder setup.

Open a shell window and navigate into your project directory with the cd command.
Before you can spin up a new DDEV project, initialize the DDEV environment with the ddev config command. In the project directory run:
```
ddev config --php-version=8.3 --omit-containers=db
```
You can run ddev config without any options, in that case the default config settings are used. Here, however, we tell DDEV
- that we want to use PHP 8.3 (which is the most current actively supported PHP version at the time of writing). If you want to run on another version, adapt this flag accordingly.
- that we want to omit spinning up a database container. Since Kirby is a flat file system that doesn't rely on a database, we don't need this container.
After you have run this command, you will find a .ddev folder inside your project folder. You might want to take a peak at the config.yml file in that folder. This gives you an idea of available config options and includes detailed explanations.

Next, run

ddev start

DDEV now creates the configured containers. When done, you will see a success message like:

All project containers are now ready.
Successfully started <yourfoldername>
Project can be reached at http://<yourfoldername>.ddev.site http://127.0.0.1:51312

And that's it, your site is now accessible at https://<foldername>.ddev.site in your browser, where <foldername> refers to the folder in which you ran the above commands. Launch the site with:
```
ddev launch
```

That was quick, right?

Alternatively, we can create a new Kirby project from scratch. Here are the steps:

Create a new project folder and use the cd command to navigate into it.
Inside the project folder, run the following commands one after the other:
```
ddev config --php-version=8.3 --omit-containers=db
ddev start
ddev composer create getkirby/starterkit
ddev launch
```
Only the third command is new, the other three we have already used above. With ddev composer we execute a composer command within the web container. ddev composer create is a special command that is adapted from composer create-project. Here we create a new Kirby Starterkit project in the current directory.

Running the ddev composer create command will delete everything in the current composer root, so be very careful where you run this command!

When possible, we recommend a public folder setup to move all files that need not be publicly accessible out of the doc root for enhanced security.

If you already have a public folder set the docroot flag to the name of your public folder, e.g. public:

ddev config --docroot=public && ddev restart

If you don't have a public folder setup yet, run:

ddev config --docroot=public --create-docroot && ddev restart

This command will create a new public folder. Then move all your assets, and the index.php into the public folder. Modify the index.php as described in our public folder documentation.

Accessing your project on other devices

By default, the <foldername>.ddev.site domain is only accessible on your local computer. To access the site from other devices on your network, you can configure the project's host_webserver_port to a port that does not conflict with already used ports on your system.

ddev config --host-webserver-port=8080 --bind-all-interfaces && ddev restart

This will configure the host-bound port to 8080 and allow it to bind to all network interfaces. Anyone on your local network can access this project’s ports.

Afterwards, you need to set the url property in Kirby's config file

/site/config/config

<?php
return [
   //… other settings
   'url' => '/'
];

You can now access the site via http://<ip>:8080 from anywhere in your local network. Replace <ip> with the IP of your computer in your local network, for example http://192.168.178.12:8080.

The best option seems to be to set url to '/' for this use case, so that links to assets etc. still work. However, when doing this, the Panel is not installable out of the box, see below.

Note that each project on your computer must use different ports, or you will run into port conflicts. Ports 80 and 443 are typically reserved by DDEV.

Server configuration

By default, DDEV runs on Nginx. The default Nginx configuration will usually work fine with Kirby. However, it does not protect the content, site or kirby folders, like Kirby's .htaccess configuration does for Apache.

In a development environment, this should not be a problem. If you want to protect your folders nonetheless, you can change the default Nginx configuration.

In .ddev/nginx_full/nginx-site.conf delete the line

#ddev-generated

And add the line:

rewrite ^\/(content|site|kirby)/(.*)$ /error last;

After each change, run ddev restart to apply the changes.

Using Apache

If your production environment runs on Apache, you might want to run your development environment on Apache as well. You can change the webserver type with the --webserver-type flag during initialization:

ddev config --webserver-type=apache-fpm && ddev restart

MailPit: Catch email locally

One of the hard parts when testing forms with sending email is that it often doesn't work as expected, emails are not sent or don't arrive.

Luckily, DDEV comes with MailPit already built-in, so you can test your forms locally with ease.

Launch the MailPit web interface with:

ddev launch -m

The try sending an email to check if it works. Make sure you don't have any SMTP transport settings configured in your config.php.

More information in the Email Capture docs.

XDebug

If you are used to use step debugging or profiling with xDebug, you will be glad to hear that it is built-in. For performance reasons, xDebug is disabled by default and you need to enable it first, then configure you IDE accordingly.

Refer to the DDEV debugging and profiling docs for details. These include detailed instructions for PHPStorm and VS Code.

A note on performance

Especially on Mac and Windows, running larger or multiple projects can become a bottleneck. Check out the tips and tricks to improve DDEV performance.

DDEV config settings

Above, we have used the ddev config command with different flags to set config options. It is worth noting that you can also change these settings manually in the .ddev/config.yaml file. Just remember to run ddev restart to apply any changes made to the configuration.

Troubleshooting

Used ports

When you get the following error message

Failed to start : unable to listen on required ports, port 80 is already in use,
Troubleshooting suggestions at https://ddev.readthedocs.io/en/stable/users/basics/troubleshooting/#unable-listen

Make sure that you have no other webserver/services running on port 80/443. Maybe you are just testing DDEV as an alternative to your MAMP, Valet, Herd… development environments. So stop those webservers before you start up DDEV.

Panel not installable

In Kirby versions prior to v4.0.3, DDEV domains were not treated as local. If you are on an older version and get an error message when trying to access the Panel, and when making the domain accessible across your network as set out above, set 'panel.install' => true in /site/config/config.php, or better still in an environment specific config file.

Other DDEV issues? Head over to the DDEV troubleshooting guide.

Other Kirby related issues: Ask us on the forum.