DDEV Add-on Template

• What is DDEV Add-on Template?
• Update Checker
• TL;DR
• Components of the repository
• Getting started
• How to debug in Github Actions
• Resources
• Credits

What is DDEV Add-on Template?

This repository is a template for providing DDEV add-ons and services.

In DDEV, add-ons can be installed from the command line using the ddev add-on get command, for example, ddev add-on get ddev/ddev-redis or ddev add-on get ddev/ddev-solr.

This repository is a quick way to get started. You can create a new repo from this one by clicking Use this template ⌄ button in the top right corner of the page.

Update Checker

Run the update checker script periodically in your add-on to verify it is up to date:

curl -fsSL https://ddev.com/s/addon-update-checker.sh | bash

TL;DR

1. Click the green Use this template ⌄ button (top right) > Create a new repository.
2. Name your repository using the ddev- prefix (e.g. ddev-foobar).
3. Add a meaningful description with relevant keywords for discoverability.
4. Click Create repository and wait for the automated "First time setup" commit.

Note

Automated updates to the README.md happen in a minute or so after creation.

5. Clone your repository locally (use the <> Code ⌄ button for the URL).
6. Prepare your add-on files and tests, see Getting started for details.
7. Create a new PR for review and discussion (avoid committing directly to main, as that bypasses the collaborative process).
8. Merge or squash your PR into main (squash is preferred for a cleaner commit history).
9. Create a new release.
10. When ready to share, make your add-on discoverable by adding the ddev-get topic.
11. Check out the DDEV Add-on Maintenance Guide.

Components of the repository

• The fundamental contents of the add-on service or other component. For example, in this template there is a docker-compose.addon-template.yaml file.
• An install.yaml file that describes how to install the service or other component.
• A test suite in test.bats that makes sure the service continues to work as expected.
• Github actions setup so that the tests run automatically when you push to the repository.

Getting started

1. Choose a good descriptive name for your add-on. It should probably start with "ddev-" and include the basic service or functionality. If it's particular to a specific CMS, perhaps ddev-<CMS>-servicename.

2. Create the new template repository by using the template button.

3. Add the files that need to be added to a DDEV project to the repository. If your add-on does not add a new service, remove docker-compose.<addon-name>.yaml file.

4. Update the install.yaml to give the necessary instructions for installing the add-on:

   • The fundamental line is the project_files directive, a list of files to be copied from this repo into the project .ddev directory.
   • You can optionally add files to the global_files directive as well, which will cause files to be placed in the global ~/.ddev directory.
   • Make sure to have the ddev_version_constraint directive, to keep the add-on users up to date.
   • Finally, pre_install_commands and post_install_commands are supported. These can use the host-side environment variables documented in DDEV docs.

5. Update tests/test.bats to provide a reasonable test for your repository. In most cases, you only need to modify the health_checks() function. Tests will run automatically on every push to the repository, and periodically each night. Please make sure to address test failures when they happen. Others will be depending on you. Bats is a testing framework that just uses Bash. To run a Bats test locally, you have to install bats-core and its libraries first. Then you download your add-on, and finally run bats ./tests/test.bats within the root of the uncompressed directory. To learn more about Bats see the documentation.

6. When everything is working, including the tests, you can push the repository to GitHub.

7. Create a release on GitHub.

8. Test manually with ddev add-on get <owner/repo>.

9. You can test PRs with ddev add-on get https://github.com/<user>/<repo>/tarball/<branch> or https://github.com/<user>/<repo>/tarball/refs/pull/<pr-number>/head.

10. You can test add-ons locally without GitHub by downloading them, making changes and running ddev add-on get /path/to/add-on-directory.

11. Update the README.md to describe the add-on, how to use it, and how to contribute. If there are any manual actions that have to be taken, please explain them. If it requires special configuration of the using project, please explain how to do those. Examples in ddev/ddev-solr, ddev/ddev-memcached, and (advanced) ddev-platformsh.

12. Add a clear short description to your repo, and add the ddev-get topic. It will immediately be added to the list provided by ddev add-on list --all and appear in the DDEV Add-on Registry within about 24 hours.

13. Once it matures and you want it to become an officially maintained add-on (i.e., supported by the DDEV team), open an issue in the DDEV issue queue.

How to debug in GitHub Actions

See full instructions.

Resources

• DDEV Add-ons: Creating, maintaining, testing (part of the DDEV Contributor Live Training)
• Advanced Add-On Techniques
• DDEV Add-on Maintenance Guide
• DDEV Documentation for Add-ons
• DDEV Add-on Registry

Credits

Contributed and maintained by @CONTRIBUTOR