generated from ddev/ddev-addon-template
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1 from mittwald/feature/initial
Initial implementation for mittwald ddev addon
- Loading branch information
Showing
10 changed files
with
242 additions
and
155 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,93 +1,49 @@ | ||
| [](https://github.com/ddev/ddev-addon-template/actions/workflows/tests.yml)  | ||
| <h1 align="center">mittwald DDEV addon</h1> | ||
|
|
||
| # ddev-addon-template <!-- omit in toc --> | ||
| <p align="center"> | ||
| <a href="#synposis">ℹ️ Synopsis</a> | | ||
| <a href="#installation">⚒️ Installation instructions</a> | | ||
| <a href="#usage">🙆 Usage</a> | ||
| </p> | ||
|
|
||
| * [What is ddev-addon-template?](#what-is-ddev-addon-template) | ||
| * [Components of the repository](#components-of-the-repository) | ||
| * [Getting started](#getting-started) | ||
| * [How to debug in Github Actions](#how-to-debug-tests-github-actions) | ||
| --- | ||
|
|
||
| ## What is ddev-addon-template? | ||
| > [!WARNING] | ||
| > Functionality of this addon depends on some unmerged features in the [mittwald CLI](https://github.com/mittwald/cli) (most importantly, https://github.com/mittwald/cli/pull/220). This warning will be removed once all required prerequisites have been merged. See https://github.com/mittwald/feature-requests/issues/118 to track the feature's overall progress. | ||
| This repository is a template for providing [DDEV](https://ddev.readthedocs.io) add-ons and services. | ||
| ## Synopsis | ||
|
|
||
| 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 contains a [DDEV addon][addon] for the mittwald hosting platform. It adds the following features to your DDEV project: | ||
|
|
||
| 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. | ||
| - Synchronizing your DDEV configuration with the current state of your mittwald cloud project | ||
| - Pulling and pushing your project's code and database contents from and to the mittwald cloud platform. | ||
| - Using the [mittwald CLI][cli] in your DDEV web environment | ||
|
|
||
|  | ||
| ## Installation | ||
|
|
||
| ## Components of the repository | ||
| This addon has the following requirements: | ||
|
|
||
| * The fundamental contents of the add-on service or other component. For example, in this template there is a [docker-compose.addon-template.yaml](docker-compose.addon-template.yaml) file. | ||
| * An [install.yaml](install.yaml) file that describes how to install the service or other component. | ||
| * A test suite in [test.bats](tests/test.bats) that makes sure the service continues to work as expected. | ||
| * [Github actions setup](.github/workflows/tests.yml) so that the tests run automatically when you push to the repository. | ||
| - DDEV (obviously) | ||
| - An API token for the [mittwald mStudio v2 API][api-intro]; you will be prompted for this token during the installation process (if not already configured) | ||
| - An existing application on the mittwald cloud; you will need the application id (formatted like `a-XXXXXX`). | ||
|
|
||
| ## 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. Globally replace "addon-template" with the name of your add-on. | ||
| 4. 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. | ||
| 5. 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, `~/.ddev`. | ||
| * Finally, `pre_install_commands` and `post_install_commands` are supported. These can use the host-side environment variables documented [in DDEV docs](https://ddev.readthedocs.io/en/latest/users/extend/custom-commands/#environment-variables-provided). | ||
|
|
||
| 6. 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](https://bats-core.readthedocs.io/en/stable/installation.html) 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](https://bats-core.readthedocs.io/en/stable/). | ||
| 7. When everything is working, including the tests, you can push the repository to GitHub. | ||
| 8. Create a [release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) on GitHub. | ||
| 9. Test manually with `ddev get <owner/repo>`. | ||
| 10. You can test PRs with `ddev get https://github.com/<user>/<repo>/tarball/<branch>` | ||
| 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](https://github.com/ddev/ddev-solr), [ddev/ddev-memcached](https://github.com/ddev/ddev-memcached), and (advanced) [ddev-platformsh](https://github.com/ddev/ddev-platformsh). | ||
| 12. Update the `README.md` header in Title Case format, for example, use `# DDEV Redis`, not `# ddev-redis`. | ||
| 13. Add a good short description to your repo, and add the [topic](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics) "ddev-get". It will immediately be added to the list provided by `ddev get --list --all`. | ||
| 14. When it has matured you will hopefully want to have it become an "official" maintained add-on. Open an issue in the [DDEV queue](https://github.com/ddev/ddev/issues) for that. | ||
|
|
||
| Add-ons were covered in [DDEV Add-ons: Creating, maintaining, testing](https://www.dropbox.com/scl/fi/bnvlv7zswxwm8ix1s5u4t/2023-11-07_DDEV_Add-ons.mp4?rlkey=5cma8s11pscxq0skawsoqrscp&dl=0) (part of the [DDEV Contributor Live Training](https://ddev.com/blog/contributor-training)). | ||
|
|
||
| Note that more advanced techniques are discussed in [DDEV docs](https://ddev.readthedocs.io/en/latest/users/extend/additional-services/#additional-service-configurations-and-add-ons-for-ddev). | ||
|
|
||
| ## How to debug tests (Github Actions) | ||
|
|
||
| 1. 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`. | ||
|
|
||
| 2. Add the following snippet to `~/.ssh/config`: | ||
| You can install this addon by running `ddev get`: | ||
|
|
||
| ``` | ||
| Host *.tmate.io | ||
| User git | ||
| AddKeysToAgent yes | ||
| UseKeychain yes | ||
| PreferredAuthentications publickey | ||
| IdentitiesOnly yes | ||
| IdentityFile ~/.ssh/tmate_ed25519 | ||
| $ ddev get mittwald/ddev | ||
| ``` | ||
| 3. Go to `https://github.com/<user>/<repo>/actions/workflows/tests.yml`. | ||
|
|
||
| 4. 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. | ||
|
|
||
|  | ||
|
|
||
| 5. After the `workflow_dispatch` event was triggered, click the `All workflows` link in the sidebar and then click the `tests` action in progress workflow. | ||
|
|
||
| 7. Pick one of the jobs in progress in the sidebar. | ||
|
|
||
| 8. Wait until the current task list reaches the `tmate debugging session` section and the output shows something like: | ||
|
|
||
| ``` | ||
| 106 SSH: ssh [email protected] | ||
| 107 or: ssh -i <path-to-private-SSH-key> [email protected] | ||
| 108 SSH: ssh [email protected] | ||
| 109 or: ssh -i <path-to-private-SSH-key> [email protected] | ||
| ``` | ||
| The installation process will prompt you for a [mittwald API token][api-intro] and your application ID. The former will be added to your global DDEV configuration, the latter to your local project configuration. | ||
|
|
||
| 9. Copy and execute the first option `ssh [email protected]` in the terminal and continue by pressing either <kbd>q</kbd> or <kbd>Ctrl</kbd> + <kbd>c</kbd>. | ||
| ## Usage | ||
|
|
||
| 10. Start the Bats test with `bats ./tests/test.bats`. | ||
| Installing the mittwald DDEV addon allows you to use the following commands: | ||
|
|
||
| For a more detailed documentation about `tmate` see [Debug your GitHub Actions by using tmate](https://mxschmitt.github.io/action-tmate/). | ||
| - `ddev pull mittwald` will download the filesystem and database contents of the linked application to your local DDEV project. | ||
| - `ddev push mittwald` will upload the filesystem and database contents back to the mittwald cloud platform. **CAUTION**: Keep in mind that this is a dangerous operation and not meant to be used as a robust, production-ready deployment solution. Have a look at our [documented deployment guides][deployment] to learn more about production-grade deployments. | ||
| - `ddev mw ...` allows you to run the [mittwald CLI][cli] in your web container. | ||
|
|
||
| **Contributed and maintained by [@CONTRIBUTOR](https://github.com/CONTRIBUTOR)** | ||
| [addon]: https://ddev.readthedocs.io/en/stable/users/extend/additional-services/ | ||
| [cli]: https://github.com/mittwald/cli | ||
| [api-intro]: https://developer.mittwald.de/docs/v2/api/intro/ | ||
| [deployment]: https://developer.mittwald.de/docs/v2/category/deployment-guides/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| #!/bin/bash | ||
|
|
||
| #ddev-generated | ||
| ## Description: Run the mw CLI inside the web container | ||
| ## Usage: mw [flags] [args] | ||
| ## Example: "mw app get" | ||
| ## ExecRaw: true | ||
|
|
||
| mw $@ |
This file was deleted.
Oops, something went wrong.
Binary file not shown.
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,63 @@ | ||
| #ddev-generated | ||
|
|
||
| auth_command: | ||
| command: | | ||
| set -eu -o pipefail | ||
| if [ -z "${MITTWALD_API_TOKEN}" ] ; then | ||
| echo "MITTWALD_API_TOKEN must be set" | ||
| exit 1 | ||
| fi | ||
| mw context set --installation-id "${MITTWALD_APP_INSTALLATION_ID}" | ||
| mw context set --project-id "$(mw app get -ojson | jq -r '.projectId')" | ||
| if ! mw app ssh --test ; then | ||
| cat <<- EOF >&2 | ||
| Could not establish an SSH connection to your space. Please make sure your SSH keys | ||
| are set up correctly; you can use the "mw app ssh --test" command to verify your | ||
| connection, and the "ddev auth ssh" command to make sure all your SSH keys are | ||
| available in your web container. | ||
| EOF | ||
| exit 1 | ||
| fi | ||
| db_pull_command: | ||
| command: | | ||
| set -eu -o pipefail | ||
| database_output="/var/www/html/.ddev/.downloads/db.sql.gz" | ||
| database_id=$(mw app get -ojson | jq -r 'if has("linkedDatabases") then ((.linkedDatabases[] | select(.purpose == "primary")).databaseId) else empty end') | ||
| if [[ -n "${database_id:-}" ]] ; then | ||
| mw database mysql dump "${database_id}" --gzip -o "${database_output}" | ||
| else | ||
| echo "app has no linked database; skipping database import" | ||
| echo "" | gzip > "${database_output}" | ||
| fi | ||
| files_import_command: | ||
| command: | | ||
| set -eu -o pipefail | ||
| mw app download --target /var/www/html | ||
| # push is a dangerous command. If not absolutely needed it's better to delete these lines. | ||
| db_push_command: | ||
| command: | | ||
| set -eu -o pipefail | ||
| pushd /var/www/html/.ddev/.downloads >/dev/null; | ||
| database_id=$(mw app get -ojson | jq -r 'if has("linkedDatabases") then ((.linkedDatabases[] | select(.purpose == "primary")).databaseId) else empty end') | ||
| if [[ -n "${database_id:-}" ]] ; then | ||
| gzip -dc db.sql.gz | mittwald database mysql import "${DATABASE_ID}" -i - | ||
| else | ||
| echo "app has no linked database; skipping database export" | ||
| fi | ||
| # push is a dangerous command. If not absolutely needed it's better to delete these lines. | ||
| files_push_command: | ||
| command: | | ||
| set -eu -o pipefail | ||
| mw app upload --source /var/www/html/ |
Oops, something went wrong.