DDEV

"DDEV is an open source tool for launching local [PHP, Python, NodeJS, etc] development environments in minutes. These environments can be extended, version controlled, and shared, so you can take advantage of a Docker workflow without Docker experience or bespoke configuration. Projects can be changed, powered down, or removed just as easily as they’re started."
GitHub | Docs

Terminology:

  • host os (windows/macosx/linux)
  • docker os (linux vm)
  • containers (linux)

General flow of ddev tech stack
[ddev, on host os] -> [docker compose -> docker, in linux vm] -> [containers, linux, managed by docker]

Install DDEV and related tools

Follow the install steps for your OS
https://ddev.readthedocs.io/en/stable/
Before running any external shell or powershell scripts, read the install script for your OS.

Prerequisites:

Windows

  • Recommended: use wsl2 and docker desktop, docker ce inside wsl (do your work mostly in windows)
  • Alternative: use wsl2, docker ce inside wsl (do your work mostly in wsl/linux)
  • Alternative: use virtual box, docker ce inside virtual box (do your work mostly in virtual box/linux)

Windows ides can access files in wsl2, but ide operations will be slower due to the different filesystems. Within wsl, for performance, do not reference files by /mnt/c/home/dev, instead use the linux file system, eg /home/dev or ~/

Install, update wsl
https://learn.microsoft.com/en-us/windows/wsl/install
https://learn.microsoft.com/en-us/windows/wsl/basic-commands

The ddev install uses chocolatey, a package manager for windows https://community.chocolatey.org/

Tip: Before installing ddev, you may want to change the default chocolatey tools install directory.
By default chocolatey installs itself to C:\ProgramData\chocolatey and installs tools to C:\tools\ (not great)
In an admin powershell, run:
[System.Environment]::SetEnvironmentVariable('ChocolateyToolsLocation','C:\ProgramData\ChocolateyTools', 'User')

Installing docker desktop may require a logout/reboot.
Ensure docker desktop is using wsl2, launch docker desktop
configure gear icon -> general -> use wsl2 based engine; resources -> wsl integration

You shouldn't need to directly access docker desktop when using ddev.

MacOSX

  • Recommended: use colima, docker ce inside colima linux os (do your work mostly in macosx)
  • Alternative: use docker desktop, docker ce inside docker desktop linux os (do your work mostly in macosx)
  • Alternative: use virtual box, docker ce inside virtual box (do your work mostly in virtual box/linux)

You shouldn't need to directly use colima when using ddev.

Linux

  • Recommended: docker ce
  • Alternative: use docker desktop

DDEV Configuration

local config
a local config file can be used to merge with the main ddev config in .ddev/config.yaml

examples:

.ddev/config.local.yaml

hooks:

    post-start:

        - exec-host: echo -e "checking bootstrapping via \033[1;34mhttp://${DDEV_HOSTNAME}/ping\033[0m"

        - exec-host: curl http://your-repo.ddev.site/ping

        - exec-host: echo -e ""

 

ddev generated files
useful to see the docker config created by ddev.
do not edit as they will be re-generated on next start

.[dot folders] 

.ddev-docker-compose-base.yaml 

.ddev-docker-compose-full.yaml 

Related DDEV Utilities

mkcert
mkcert is a simple tool for making locally-trusted development certificates. eg allows local https without browser warnings
https://github.com/FiloSottile/mkcert

firefox
The non chrome browser
https://www.mozilla.org/en-US/firefox/new/
for ssl access to ddev sites, import the mkcert generated ca cert

  • list CA location, > mkcert -CAROOT
  • in firefox url, about:preferences#privacy
  • filter, certificates
  • View Certificates -> Authorities -> Import
  • Select the rootCA.pem file
  • find the imported cert in the list, find mkcert
  • click Edit Trust, click enable for websites

ngrok
ngrok is a reverse proxy that creates a secure tunnel from a public endpoint to a locally running web service eg expose a local server behind a NAT or firewall to the internet
https://ngrok.com/

chocolatey
a package manager for windows

docker
container management docker ce is opensource, docker desktop is a subscription
https://docs.docker.com/engine/install/ubuntu/

mutagen
mutagen provides real-time file synchronization and flexible network forwarding for developers, extending the reach of local development tools to cloud-based containers and infrastructure. initial file sync can take a bit https://mutagen.io/

maxosx and windows:
Accessing lots of files between the host os and linux os can be slow due to the different filesystems. mutagen will perform a two-way sync between your os and the ddev managed docker container.
https://ddev.readthedocs.io/en/stable/users/install/performance/#mutagen

traefik
dddev routing ddev-router has been based on a forked, poorly-documented nginx reverse proxy. Versions after DDEV v1.21.3 add a new router based on the popular Traefik Proxy.
https://ddev.readthedocs.io/en/latest/users/configuration/experimental/#traefik-router
https://traefik.io/traefik/

podman
container management, opensource, compatible with docker
https://podman.io/

phpstorm
php, code ide
https://www.jetbrains.com/phpstorm/
a ddev plugin exists for phpstorm and webstorm, which can facilitate setting up xdebug, server, php config, stop/start ddev, etc
https://ddev.readthedocs.io/en/latest/users/install/phpstorm/#phpstorm-basic-setup-on-windows-wsl2
using ddev from the command line may be simpler and more consistent

vscode
code ide
https://code.visualstudio.com/

General ddev, docker, and container tips

  • manage ddev within the host windows/macosx os, and if needed manage docker ce via the cli within the linux vm (wsl for windows)
  • one container per repo
    • changes inside container will not persist, as it is a container
    • any changes need to be made outside of container (code), or to ddev config (container services, config)
    • ddev configuration is stored in the relative directory .ddev/
    • to facilitate ddev updates, try to keep config changes to a minimal
  • start project
    > ddev start
    initial file sync can take a bit
  • stop project
    > ddev stop
  • project details
    > ddev status
    > ddev describe
  • list docker images
    inside linux host
    > docker ps
  • show all projects
    > ddev list
  • stop all containers
    > ddev poweroff
  • restart a project
    often used after making .ddev config changes
    > ddev restart
  • ddev images are debian based
    ssh into container to test or view config
    reminder, changes inside container will not persist
    > ddev ssh
  • control processes, php-fpm, nginx, node
    ddev uses supervisorctl to control processes, as opposed to systemctl; inside linux host
    > supervisorctl restart php-fpm
    > supervisorctl restart nginx
    note, if a process dies or attempts to restart several times due to bad config, the container will stop.
  • start npm run start command
    > ddev npm run start
  • stop npm run start command
    > ddev npm run stop
  • run phpstan
    > ddev composer phpstan
  • view logs from host os
    > ddev logs
  • view logs inside container
    > ddev ssh
    > vi [log]
    > tail -f [log]
  • docker maintenance
    Sometimes, either due to bad ddev, docker, wsl, comila, or normal config/docker changes, you may end up with unused, disconnected images, containers.
    To clean up your system, and recover some storage; inside your linux host
    > docker system prune
  • if ddev container won't start after config changes
    Fix or revert config changes, then
    > ddev restart
    "generally removes most things that need to be removed"
    > ddev poweroff
    > ddev rm -a
  • if start multiple ddev containers at the same time, there may be port conflicts as they may try to grab the same 'random' or initial default port; either restart failed container, or add a pause between container starts
  • check open ports in linux host
    > ss -l

-End of Document-
Thanks for reading