From e35075181609205f97da1a54f567332996e3e24d Mon Sep 17 00:00:00 2001 From: ochorocho Date: Tue, 17 Oct 2023 21:54:46 +0200 Subject: [PATCH] Port rabbitmq from ddev-contrib to be used with "ddev get" --- README.md | 102 ++++++++--------------------- docker-compose.addon-template.yaml | 16 ----- docker-compose.rabbitmq.yaml | 28 ++++++++ install.yaml | 6 +- rabbitmq-build/enabled_plugins | 1 + 5 files changed, 59 insertions(+), 94 deletions(-) delete mode 100644 docker-compose.addon-template.yaml create mode 100644 docker-compose.rabbitmq.yaml create mode 100644 rabbitmq-build/enabled_plugins diff --git a/README.md b/README.md index 7199666..4efe271 100644 --- a/README.md +++ b/README.md @@ -1,91 +1,43 @@ -[![tests](https://github.com/ddev/ddev-addon-template/actions/workflows/tests.yml/badge.svg)](https://github.com/ddev/ddev-addon-template/actions/workflows/tests.yml) ![project is maintained](https://img.shields.io/maintenance/yes/2024.svg) +# RabbitMQ -# ddev-addon-template +This enables a RabbitMQ service container that can be used by other containers on the same network and the host +machine itself. -* [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-in-github-actions) - -## What is ddev-addon-template? - -This repository is a template for providing [DDEV](https://ddev.readthedocs.io) 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. - -![template button](images/template-button.png) - -## 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](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. - -## 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--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 remove `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/stable/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.bat`, 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 on GitHub. -9. Test manually with `ddev get `. -10. You can test PRs with `ddev get https://github.com///tarball/` -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](github.com/ddev/ddev-memcached), and (advanced) [ddev-platformsh](https://github.com/ddev/ddev-platformsh). -12. Add a good short description to your repo, and add the label "ddev-get". It will immediately be added to the list provided by `ddev get --list --all`. -13. 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. - -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 a SSH-key registered with Github. You either pick the key you already authenticate 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` +## Installation ``` -Host *.tmate.io - User git - AddKeysToAgent yes - UseKeychain yes - PreferredAuthentications publickey - IdentitiesOnly yes - IdentityFile ~/.ssh/tmate_ed25519 +ddev get ochorocho/ddev-rabbitmq && ddev restart ``` -3. Go to `https://github.com///actions/workflows/tests.yml`. -4. Click the `Run workflow`- button and you will have the option to the select the branch to run the workflow from and activate `tmate` by checking the `Debug with tmate` checkbox for this run. +The [rabbitmq-build](rabbitmq-build) directory contains the enabled plugins, these are required for having a functioning +RabbitMQ service, as the container would otherwise stop itself shortly after starting. The plugins themselves are what +enables the management UI and the graphs within it. -![tmate](images/gh-tmate.jpg) +## Configuration -5. After the `workflow_dispatch`-event was triggered click the `All workflows`-link in the sidebar and then click the in progress workflow `tests`. +From within the container, the RabbitMQ container is reached at hostname: `ddev--rabbitmq`, port: 5672, so +the server URL might be `amqp://ddev--rabbitmq:5672`. -7. Pick one of the jobs in progress in the sidebar. +For more details check the connection section below. -8. Wait until the current task list reaches the `tmate debugging session` section and the output shows something like: +## Connection -``` -106 SSH: ssh PRbaS7SLVxbXImhjUqydQBgDL@nyc1.tmate.io -107 or: ssh -i PRbaS7SLVxbXImhjUqydQBgDL@nyc1.tmate.io -108 SSH: ssh PRbaS7SLVxbXImhjUqydQBgDL@nyc1.tmate.io -109 or: ssh -i PRbaS7SLVxbXImhjUqydQBgDL@nyc1.tmate.io -``` +RabbitMQ is accessible from the host machine itself as well as between the containers on the same network, and comes +with a nice management UI for ease of use. + +__Important:__ If you need to run multiple ddev sites that use this RabbitMQ service, you will have to alter the ports +per site in the [docker-compose.rabbitmq.yaml](docker-compose.rabbitmq.yaml). + +### Management UI -9. Copy and execute the first option `ssh PRbaS7SLVxbXImhjUqydQBgDL@nyc1.tmate.io` in the terminal and continue by pressing either `q` or `ctrl-c`. +The management UI can be accessed through `http://.ddev.site:15672` on the host machine. +Username "rabbitmq", password "rabbitmq". -10. Start the bats test with `bats tests/test.bats`. +### AMQP protocol access -For a more detailed documentation about `tmate` see [Debug your GitHubActions by using tmate](https://mxschmitt.github.io/action-tmate/) +You can access the RabbitMQ service through it's AMQP protocol two ways: +* From the host machine: `amqp://.ddev.site:5672` +* From docker containers on the same docker network (ddev_default): `amqp://ddev--rabbitmq:5672` -**Contributed and maintained by [@CONTRIBUTOR](https://github.com/CONTRIBUTOR)** +**Originally by [@Graloth](https://github.com/Graloth)** diff --git a/docker-compose.addon-template.yaml b/docker-compose.addon-template.yaml deleted file mode 100644 index 09a8a5f..0000000 --- a/docker-compose.addon-template.yaml +++ /dev/null @@ -1,16 +0,0 @@ -#ddev-generated -# Simple template to demonstrate addon-template -services: - addon-template: - container_name: ddev-${DDEV_SITENAME}-addon-template - image: busybox:stable - command: tail -f /dev/null - networks: [default, ddev_default] - restart: "no" - # These labels ensure this service is discoverable by ddev. - labels: - com.ddev.site-name: ${DDEV_SITENAME} - com.ddev.approot: $DDEV_APPROOT - - volumes: - - ".:/mnt/ddev_config" diff --git a/docker-compose.rabbitmq.yaml b/docker-compose.rabbitmq.yaml new file mode 100644 index 0000000..95e3f48 --- /dev/null +++ b/docker-compose.rabbitmq.yaml @@ -0,0 +1,28 @@ +#ddev-generated +version: '3.6' +services: + rabbitmq: + container_name: ddev-${DDEV_SITENAME}-rabbitmq + hostname: ${DDEV_SITENAME}-rabbitmq + image: "rabbitmq:3-management" + expose: + - 15672 + environment: + - VIRTUAL_HOST=$DDEV_HOSTNAME + - HTTP_EXPOSE=15672 + - HTTPS_EXPOSE=15673:15672 + - RABBITMQ_ERLANG_COOKIE=SWQOKODSQALRPCLNMEQG + - RABBITMQ_DEFAULT_USER=rabbitmq + - RABBITMQ_DEFAULT_PASS=rabbitmq + - RABBITMQ_DEFAULT_VHOST=/ + labels: + com.ddev.site-name: ${DDEV_SITENAME} + com.ddev.approot: $DDEV_APPROOT + volumes: + - "./rabbitmq-build/enabled_plugins:/etc/rabbitmq/enabled_plugins" + - ".:/mnt/ddev_config" + web: + links: + - rabbitmq:rabbitmq +volumes: + rabbitmq: diff --git a/install.yaml b/install.yaml index b3e394a..a60475d 100644 --- a/install.yaml +++ b/install.yaml @@ -1,6 +1,6 @@ # Details about the install.yaml file are at https://ddev.readthedocs.io/en/latest/users/extend/additional-services/#sections-and-features-of-ddev-get-add-on-installyaml -name: your-addon +name: rabbitmq # pre_install_actions - list of actions to run before installing the addon. # Examples would be removing an extraneous docker volume, @@ -58,8 +58,8 @@ pre_install_actions: # if it hasn't been modified by the user. # DDEV environment variables can be interpolated into these filenames project_files: -- docker-compose.addon-template.yaml -# - extra_files/ + - docker-compose.rabbitmq.yaml + - ./rabbitmq-build # - somefile.sh # List of files and directories that are copied into the global .ddev directory diff --git a/rabbitmq-build/enabled_plugins b/rabbitmq-build/enabled_plugins new file mode 100644 index 0000000..2a007f8 --- /dev/null +++ b/rabbitmq-build/enabled_plugins @@ -0,0 +1 @@ +[rabbitmq_management, rabbitmq_management_visualiser].