Skip to content

Local testing with DDEV

Michael Wynne edited this page Sep 16, 2026 · 3 revisions

Install Mukurtu with DDEV

Using DDEV is the easiest way to get up and running with Mukurtu locally.

  • Download and install DDEV
  • Make a new folder in which to work and initialize a DDEV project inside it. Run the following commands to download and install Mukurtu.
mkdir mukurtu
cd mukurtu
ddev config --project-type=drupal --docroot=web
# Optional but recommended: install pdftotext inside the DDEV container:
echo "RUN sudo apt -qq update; sudo apt install poppler-utils -y;" > .ddev/web-build/Dockerfile.pdftotext
ddev start
ddev composer create-project mukurtu/mukurtu-template:dev-main
ddev drush si --site-name=Mukurtu --account-name=admin --account-pass=admin
ddev launch

Updating Mukurtu CMS for Development (DDEV)

  • Install Mukurtu using the normal DDEV installation steps (see the README.md).
  • Remove the composer-installed Mukurtu and replace with a git checkout:

From project root:

rm -rf web/profiles/mukurtu mukurtu-src
git clone -b <branch> git@github.com:MukurtuCMS/Mukurtu-CMS.git mukurtu-src
ddev composer config repositories.local-dev \
  '{"type":"path","url":"mukurtu-src","options":{"symlink":false,"versions":{"mukurtu/mukurtu":"4.9999.9999"}}}'
ddev composer upgrade mukurtu/mukurtu -W
ddev composer upgrade -W
ddev drush updb -y && ddev drush cr
  • Now changes to the web/profiles/mukurtu/composer.json file will affect the overall project.

Or, clone the whole repo, and checkout branches as needed.

rm -rf web/profiles/mukurtu mukurtu-src
git clone git@github.com:MukurtuCMS/Mukurtu-CMS.git mukurtu-src
ddev composer config repositories.local-dev \
  '{"type":"path","url":"mukurtu-src","options":{"symlink":false,"versions":{"mukurtu/mukurtu":"4.9999.9999"}}}'
cd mukurtu-src && git checkout <branch_name> && cd ..
ddev composer upgrade mukurtu/mukurtu -W
ddev composer upgrade -W
ddev drush updb -y && ddev drush cr

Why the versions option is required

Composer derives a path package's version from its current git branch, which gives something like dev-<branch_name>. That can't satisfy this project's "mukurtu/mukurtu": "^4.0" constraint. A path repository is also canonical by default, so Composer won't fall back to the tagged release on Packagist to cover the gap; it just fails to resolve with a "repository is canonical" error. The "versions":{"mukurtu/mukurtu":"4.9999.9999"} option pins the path package to a version high enough to satisfy ^4.0, no matter which 4.x branch is checked out. Don't remove this option or the install will fail. CI and Tugboat use the same alias for the same reason.

Also use mukurtu/mukurtu, not mukurtu/*, in the composer upgrade command. In zsh, mukurtu/* is treated as a filesystem glob and fails with "no matches found" instead of being passed to Composer. The ddev composer upgrade -W that follows still picks up the change, so this mistake is easy to miss, but it means the first command silently does nothing.

If you see "The profile mukurtu does not exist" after this

If web/profiles/mukurtu was ever deleted and a drush command ran against the site before the profile was restored (for example, while debugging the versions option above), Drupal may permanently cache an incomplete profile list. If drush cache:rebuild doesn't clear the error, clear the stale entry directly:

ddev drush sql-query "DELETE FROM key_value WHERE collection='state' AND name='system.profile.files';"
ddev drush cr

This is a one-time repair for a site that already hit the problem. It shouldn't recur if the versions option is in place from the start.

Updating Composer Dependencies

When using ddev composer, it will always modify the root composer.json file, regardless of which directory the terminal is in. So in order to add a new dependency to web/profiles/mukurtu/composer.json, the path must be passed to composer, such as this:

ddev composer require drupal/example --working-dir=web/profiles/mukurtu --no-update --no-install

And then the root composer can take it into account and install it with:

ddev composer update

Because adding a dependency is so verbose to do via command line, it may be easier to simply edit the composer.json file to add a dependency. Either way, a composer.lock file should only be generated at the root level, not within the install profile directory.

Clone this wiki locally