Per-project DDEV config via symlinks for WordPress sites: intended usage and best practices?

[raphaelportmann]

We use DDEV for a wide range of projects and would like to get some input on two scenarios where we're not sure if our approach is how DDEV is meant to be used, or if there are best practices we should follow instead.

We mainly build WordPress sites. Newer projects use Bedrock, so the whole application including the DDEV configuration (a .ddev directory at the project root) lives in a single git repository. No questions about that setup, it works exactly as intended.

Scenario 1: Legacy sites where only the theme is in git

For older sites, only the theme (and sometimes plugins) is version-controlled. The full site only exists on the server and is set up locally from scratch or synchronized down. To still have a per-project DDEV configuration under version control, we keep the .ddev directory inside the theme repository and symlink it to the site root:

site-root/                          <- local site, not in git
├── .ddev  ->  symlink to web/wp-content/themes/my-theme/.ddev
├── wp-admin/
├── wp-includes/
├── wp-content/
│   ├── plugins/
│   ├── uploads/
│   └── themes/
│       └── my-theme/         <- git repository
│           ├── .ddev/              <- actual DDEV config, checked in
│           │   └── config.yaml
│           ├── assets/
│           ├── templates/
│           └── functions.php
└── wp-config.php

Questions:

• Is a symlinked .ddev directory an intended/supported way to do this?
• Are there limitations we should know about? The only one we've run into so far is that DDEV commands can't be run from inside the theme directory itself, because DDEV tries to treat it as a new project and fails since a project with the same name already exists. In practice this hasn't been a problem. We run everything from the site root, use ddev exec npm ... together with working_dir: web: /path/to/theme, or ddev ssh for theme-specific build commands.

Scenario 2: One site, multiple themes/plugins developed in parallel

Some projects have multiple themes and/or plugins that are developed in parallel. These are mostly multisites, or sites where functionality is split across several plugins instead of a single theme. Since they run as one site on one server, we also set up a single DDEV project locally. To avoid having multiple DDEV configurations, the most central theme/plugin repository holds the "main" .ddev config, which is symlinked to the site root:

site-root/                          <- local site, not in git
├── .ddev  ->  symlink to web/wp-content/themes/main-theme/.ddev
├── wp-content/
│   ├── themes/
│   │   ├── main-theme/             <- git repo A ("main", owns .ddev)
│   │   │   ├── .ddev/
│   │   │   │   ├── config.yaml
│   │   │   │   ├── config.python2.yaml
│   │   │   │   ├── docker-compose.python2.yaml
│   │   │   │   └── web-build/
│   │   │   │       ├── Dockerfile
│   │   │   │       └── Dockerfile.python2
│   │   │   └── ...
│   │   └── secondary-theme/        <- git repo B (no .ddev)
│   │       └── ...
│   └── plugins/
│       ├── custom-plugin-one/      <- git repo C (no .ddev)
│       └── custom-plugin-two/      <- git repo D (no .ddev)
└── wp-config.php

This works fairly well. working_dir definitions don't really make sense here since there are multiple working directories. Issues mostly come up when the themes/plugins would need different DDEV configurations. Webserver, PHP and DB versions aren't a problem because they have to match anyway, as everything runs against the same server. What we did run into are different Node versions for the build processes. Our solution is the nvm add-on to switch between the required versions. For some legacy builds we'll also need the python2 add-on, and we're not sure if running python2 and python3 side by side could cause issues as npm setup might not require the specific version.

Questions:

• Does this single-project setup make sense, or would a project-per-theme/plugin approach be better?
• Would it be possible to run multiple DDEV projects on the same WordPress application files, and ideally the same database? Symlinking the files and either syncing the databases or sharing one database comes to mind.

We're happy about any input from community members with similar use cases, and ideally some insight from maintainers on whether these setups are safe long-term or likely to break when future updates don't have them in mind.

This post was edited and refined with assistance from GitHub Copilot.

[nickchomey]

I don't really have any feedback for you, but what I do for WordPress is have the entire project in git and wp in its own subdirectory

project/
- .git
- .ddev
- wp/
-- wp-content/
etc

Even wp core is in version control like this.

I do it because I apply patches to wp core, various plugins etc...

You also can't use composer/packagist for most "premium" plugins - so I just do all updates via the WP updater. I have a custom mu plugin that creates a new commit for each plugin, theme, core or language update when triggered from the WP updater.

I also have some other directories within project root with other things - experiments, some microservices etc

Though, I also have a few plugins that are an actual git repo because I've cloned them from upstream to be able to make contributions to it. Perhaps I could use a submodule for that, but I find those to be cumbersome/(human) error prone

It's one big monorepo. I found that works better than various distinct repos because sometimes related changes span more than one plugin etc

I don't really recommend this, but just sharing what I do. It should also be noted that it's a highly custom site rather than a more typical

[raphaelportmann]

Thanks for sharing your approach. I agree that it's a bit unconventional, but I can see how it works in your case.

For new projects, we use Bedrock (composer-based installation for core, plugins, etc.) - which is definitely the way to go. For premium plugins, there are solutions like SatisPress or paid SaaS options.

This discussion mostly centers around projects where a DDEV environment is needed without the possibility to migrate to a fully source-controlled application.

[nickchomey]

Satispress and paid options seem much more complicated to me. But to each their own!

[stasadev]

Hi @raphaelportmann,

Is a symlinked .ddev directory an intended/supported way to do this?

This isn't a supported approach, at least we don't have any tests for it.

Are there limitations we should know about? The only one we've run into so far is that DDEV commands can't be run from inside the theme directory itself, because DDEV tries to treat it as a new project and fails since a project with the same name already exists.

You'll need to remove name: from your theme's .ddev/config.yaml to make DDEV commands work. Read more about it here: https://docs.ddev.com/en/stable/users/configuration/config/#omit_project_name_by_default

Our solution is the nvm add-on to switch between the required versions.

node_version also supports this (scroll down to "Installing additional Node.js versions"): https://docs.ddev.com/en/stable/users/configuration/config/#nodejs_version

But if nvm works, that's fine too.

For some legacy builds we'll also need the python2 add-on, and we're not sure if running python2 and python3 side by side could cause issues as npm setup might not require the specific version.

If npm calls python2 or python3 explicitly, there shouldn't be any conflicts.

---

Does this single-project setup make sense, or would a project-per-theme/plugin approach be better?

From what I've read, both approaches make sense.

Would it be possible to run multiple DDEV projects on the same WordPress application files, and ideally the same database? Symlinking the files and either syncing the databases or sharing one database comes to mind.

You can share a database between projects: https://docs.ddev.com/en/stable/users/usage/managing-projects/#inter-project-communication

[raphaelportmann]

Thanks for your detailed feedback, @stasadev!

Would you be interested in adding tests to check whether a symlinked .ddev config folder works, or even adding documentation around this? It's probably not widely used. Since symlinks are implemented at a really low filesystem level, it's also unlikely that DDEV handles them differently, as they're seen as a normal file structure.

It isn't even necessary to remove the project name. We wouldn't want 2 different projects - it just fails when using symlinks because the original config folder is located inside a subfolder of the project itself, and DDEV isn't aware that it's symlinked to the project root. Commands then fail inside that subfolder because DDEV tries to use that folder as the project root. Using a different name for the original folder would probably be an easy fix for this so DDEV doesn't recognize it.

Using multiple Node versions with n is definitely the way to go; we will look into it. Thanks for pointing to it. Also, python2 and python3 simultaneously should work fine.

I think deciding between a single-project or per-theme/plugin approach depends on the complexity of the project and on whether one configuration can cover all parts of it. So I agree - both make sense. We will definitely look into shared databases.

[stasadev]

Would you be interested in adding tests to check whether a symlinked .ddev config folder works, or even adding documentation around this?

I'll make a note to check that.

[rfay]

You're pioneering great stuff, and your expertise is most important. Let us know if your basic questions are sorted out, and we're happy to continue the conversation here or in discord.

As a general idea that I'm sure you'd agree with, try to get all sites completely under source control.

[raphaelportmann]

Thanks! I'll look into joining Discord. I wanted to keep the discussion here so it's easily searchable and publicly accessible.

I completely agree. We've already switched to WordPress Bedrock for that reason, and we'll also be exploring how to onboard legacy projects onto it. However, given the volume of legacy projects, this migration will take considerable time and likely won't ever be fully completed - so a solution for these projects is still necessary.

Overall, we're really happy with how DDEV simplifies the process, and our workaround has been effective in making things run smoothly.