This repository is a template for providing DDEV add-ons and services.
In DDEV addons can be installed from the command line using the ddev get
command, for example, ddev get ddev/ddev-redis
or ddev get ddev/ddev-solr
.
This repository is a quick way to get started. You can create a new repo from this one by clicking the template button in the top right corner of the page.
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
.
Create the new template repository by using the template button.
Globally replace "addon-template" with the name of your add-on.
Add the files that need to be added to a DDEV project to the repository. For example, you might replace docker-compose.addon-template.yaml
with the docker-compose.*.yaml
for your recipe.
Update the install.yaml
to give the necessary instructions for installing the add-on:
project_files
directive, a list of files to be copied from this repo into the project .ddev
directory.global_files
directive as well, which will cause files to be placed in the global .ddev
directory, ~/.ddev
.pre_install_commands
and post_install_commands
are supported. These can use the host-side environment variables documented in DDEV docs.Update tests/test.bats
to provide a reasonable test for your repository. Tests are triggered either by manually executing bats ./tests/test.bats
, automatically on every push to the repository, or periodically each night. Please make sure to attend to test failures when they happen. Others will be depending on you. Bats is a simple testing framework that just uses Bash. To run a Bats test locally, you have to install bats-core 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.
When everything is working, including the tests, you can push the repository to GitHub.
Create a release on GitHub.
Test manually with ddev get <owner/repo>
.
You can test PRs with ddev get https://github.com/<user>/<repo>/tarball/<branch>
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.
Update the README.md
header in Title Case format, for example, use # DDEV Redis
, not # ddev-redis
.
Add a good short description to your repo, and add the topic "ddev-get". It will immediately be added to the list provided by ddev get --list --all
.
When it has matured you will hopefully want to have it become an "official" maintained add-on. Open an issue in the DDEV queue for that.
Add-ons were covered in DDEV Add-ons: Creating, maintaining, testing (part of the DDEV Contributor Live Training).
Note that more advanced techniques are discussed in Advanced Add-On Techniques and DDEV docs.
You need an SSH-key registered with GitHub. You either pick the key you have already used with github.com
or you create a dedicated new one with ssh-keygen -t ed25519 -a 64 -f tmate_ed25519 -C "$(date +'%d-%m-%Y')"
and add it at https://github.com/settings/keys
.
Add the following snippet to ~/.ssh/config
:
Host *.tmate.io
User git
AddKeysToAgent yes
UseKeychain yes
PreferredAuthentications publickey
IdentitiesOnly yes
IdentityFile ~/.ssh/tmate_ed25519
Go to https://github.com/<user>/<repo>/actions/workflows/tests.yml
.
Click the Run workflow
button and you will have the option to select the branch to run the workflow from and activate tmate
by checking the Debug with tmate
checkbox for this run.
After the workflow_dispatch
event was triggered, click the All workflows
link in the sidebar and then click the tests
action in progress workflow.
Pick one of the jobs in progress in the sidebar.
Wait until the current task list reaches the tmate debugging session
section and the output shows something like:
106 SSH: ssh PRbaS7SLVxbXImhjUqydQBgDL@nyc1.tmate.io
107 or: ssh -i <path-to-private-SSH-key> PRbaS7SLVxbXImhjUqydQBgDL@nyc1.tmate.io
108 SSH: ssh PRbaS7SLVxbXImhjUqydQBgDL@nyc1.tmate.io
109 or: ssh -i <path-to-private-SSH-key> PRbaS7SLVxbXImhjUqydQBgDL@nyc1.tmate.io
Copy and execute the first option ssh PRbaS7SLVxbXImhjUqydQBgDL@nyc1.tmate.io
in the terminal and continue by pressing either q or Ctrl + c.
Start the Bats test with bats ./tests/test.bats
.
For a more detailed documentation about tmate
see Debug your GitHub Actions by using tmate.
Contributed and maintained by @CONTRIBUTOR