Skip to content

Commit c89822f

Browse files
texnixetexnixe
committed
Add DDEV cookbook recipe
1 parent 0354858 commit c89822f

File tree

1 file changed

+229
-0
lines changed

1 file changed

+229
-0
lines changed

‎content/docs/2_cookbook/9_setup/0_ddev/cookbook-recipe.txt

+229
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
Title: Kirby meets DDEV
2+
3+
----
4+
5+
Published: 2024-02-04
6+
7+
----
8+
9+
Description: Set up a local development environment for Kirby with DDEV in no time.
10+
11+
----
12+
13+
Authors: - authors/sonja-broda
14+
15+
----
16+
17+
Text:
18+
19+
(link: https://ddev.com/ text: 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.
20+
21+
So basically, it provides a Docker environment without you having to know anything about using Docker, unless you want to configure your own services.
22+
23+
24+
## Requirements
25+
26+
1. DDEV uses (link: https://www.docker.com/ text: 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 (link: https://ddev.readthedocs.io/en/stable/users/install/docker-installation/ text: Docker providers) recommended for your operating system.
27+
2. You can use an existing project, or download/clone a Kirby Starterkit. We will also show how to install the Starterkit via DDEV.
28+
3. Make sure you don't have any other services running on port 80, so stop your current webserver if its using this port.
29+
30+
## Install DDEV
31+
32+
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 (link: https://ddev.com/get-started/ text: installation instructions) for each operating system. Simply follow these instructions and then head back here.
33+
34+
Once DDEV is installed and running, setting up a project is done with a few quick steps.
35+
36+
**TL;DR**
37+
1. Clone or download the code for your project.
38+
2. `cd` into the project directory and run `ddev config` to initialize a DDEV project.
39+
3. Run `ddev start` to spin up the project.
40+
4. Run `ddev launch` to open your project in a browser.
41+
42+
But let's go through these general steps in a little more detail and see how we can customize them for our needs.
43+
44+
## Starting from an existing project
45+
46+
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 (link: #public-folder-setup text: Public folder setup).
47+
48+
1. Open a shell window and navigate into your project directory with the `cd` command.
49+
2. Before you can spin up a new DDEV project, initialize the DDEV environment with the `ddev config` command. In the project directory run:
50+
51+
```bash
52+
ddev config --php-version=8.3 --omit-containers=db
53+
```
54+
 
55+
You can run `ddev config` without any options, in that case the default config settings are used. Here, however, we tell DDEV
56+
* 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.
57+
* 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.
58+
59+
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.
60+
61+
62+
3. Next, run
63+
64+
```bash
65+
ddev start
66+
```
67+
68+
DDEV now creates the configured containers. When done, you will see a success message like:
69+
70+
```bash
71+
All project containers are now ready.
72+
Successfully started <yourfoldername>
73+
Project can be reached at http://<yourfoldername>.ddev.site http://127.0.0.1:51312
74+
```
75+
&nbsp;
76+
77+
4. 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:
78+
79+
```bach
80+
ddev launch
81+
```
82+
83+
That was quick, right?
84+
85+
## Spinning up a fresh Starterkit via composer command
86+
87+
Alternatively, we can create a new Kirby project from scratch. Here are the steps:
88+
89+
1. Create a new project folder and use the `cd` command to navigate into it.
90+
2. Inside the project folder, run the following commands one after the other:
91+
92+
```bash
93+
ddev config --php-version=8.3 --omit-containers=db
94+
ddev start
95+
ddev composer create getkirby/starterkit
96+
ddev launch
97+
```
98+
99+
&nbsp;
100+
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.
101+
102+
<warning>
103+
Running the `ddev composer create` command will delete everything in the current composer root, so be very careful where you run this command!
104+
</warning>
105+
106+
## Public folder setup
107+
108+
When possible, we recommend a (link: docs/guide/configuration#custom-folder-setup__public-folder-setup text: public folder setup) to move all files that need not be publicly accessible out of the doc root for enhanced security.
109+
110+
If you already have a public folder set the `docroot` flag to the name of your public folder, e.g. `public`:
111+
112+
```bash
113+
ddev config --docroot=public && ddev restart
114+
```
115+
116+
If you don't have a public folder setup yet, run:
117+
118+
```bash
119+
ddev config --docroot=public --create-docroot && ddev restart
120+
```
121+
122+
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 (link: ocs/guide/configuration#custom-folder-setup__public-folder-setup text: public folder documentation).
123+
124+
125+
## Accessing your project on other devices
126+
127+
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.
128+
129+
```bash
130+
ddev config --host-webserver-port=8080 --bind-all-interfaces && ddev restart
131+
```
132+
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.
133+
134+
Afterwards, you need to set the `url` property in Kirby's config file
135+
136+
```php "/site/config/config"
137+
<?php
138+
return [
139+
//… other settings
140+
'url' => '/'
141+
];
142+
```
143+
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`.
144+
145+
146+
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 (link: #panel-not-installable text: below).
147+
148+
149+
<info>
150+
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.
151+
</info>
152+
## Server configuration
153+
154+
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.
155+
156+
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.
157+
158+
In `.ddev/nginx_full/nginx-site.conf` delete the line
159+
160+
```
161+
#ddev-generated
162+
```
163+
164+
And add the line:
165+
166+
```
167+
rewrite ^\/(content|site|kirby)/(.*)$ /error last;
168+
```
169+
After each change, run `ddev restart` to apply the changes.
170+
171+
### Using Apache
172+
173+
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:
174+
175+
```bash
176+
ddev config --webserver-type=apache-fpm && ddev restart
177+
```
178+
179+
## MailPit: Catch email locally
180+
181+
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.
182+
183+
Luckily, DDEV comes with MailPit already built-in, so you can test your forms locally with ease.
184+
185+
Launch the MailPit web interface with:
186+
187+
```bash
188+
ddev launch -m
189+
```
190+
The try (link: https://getkirby.com/docs/guide/emails#simple text: sending an email) to check if it works. Make sure you don't have any SMTP transport settings configured in your `config.php`.
191+
192+
More information in the (link: https://ddev.readthedocs.io/en/stable/users/usage/developer-tools/#email-capture-and-review-mailpit text: Email Capture docs).
193+
194+
## XDebug
195+
196+
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.
197+
198+
Refer to the (link: https://ddev.readthedocs.io/en/stable/users/debugging-profiling/step-debugging/ text: DDEV debugging and profiling docs) for details. These include detailed instructions for PHPStorm and VS Code.
199+
200+
## A note on performance
201+
202+
Especially on Mac and Windows, running larger or multiple projects can become a bottleneck. Check out the tips and tricks (link: https://ddev.readthedocs.io/en/stable/users/install/performance/ text: to improve DDEV performance).
203+
204+
## DDEV config settings
205+
206+
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.
207+
208+
## Troubleshooting
209+
210+
### Used ports
211+
212+
When you get the following error message
213+
214+
> Failed to start <projectfolder>: unable to listen on required ports, port 80 is already in use,
215+
Troubleshooting suggestions at https://ddev.readthedocs.io/en/stable/users/basics/troubleshooting/#unable-listen
216+
217+
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.
218+
219+
### Panel not installable
220+
221+
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 (link: text: environment specific config file).
222+
223+
224+
Other DDEV issues? Head over to the (link: https://ddev.readthedocs.io/en/stable/users/usage/troubleshooting/ text: DDEV troubleshooting guide).
225+
226+
Other Kirby related issues: Ask us (link: forum.getkirby.com text: on the forum).
227+
228+
229+

0 commit comments

Comments
 (0)