diff --git a/rabbitmq/content.md b/rabbitmq/content.md index 66071e31d1ce..c4e14bb293ee 100644 --- a/rabbitmq/content.md +++ b/rabbitmq/content.md @@ -29,50 +29,46 @@ This will start a RabbitMQ container listening on the default port of 5672. If y Note the `database dir` there, especially that it has my "Node Name" appended to the end for the file storage. This image makes all of `/var/lib/rabbitmq` a volume by default. -### Memory Limits - -RabbitMQ contains functionality which explicitly tracks and manages memory usage, and thus needs to be made aware of cgroup-imposed limits. - -The upstream configuration setting for this is `vm_memory_high_watermark`, and it is described under ["Memory Alarms"](https://www.rabbitmq.com/memory.html) in the documentation. - -In this image, this value is set via `RABBITMQ_VM_MEMORY_HIGH_WATERMARK`. The value of this environment variable is interpreted as follows: - -- `0.49` is treated as `49%`, just like upstream (`{ vm_memory_high_watermark, 0.49 }`) -- `56%` is treated as `56%` (`0.56`; `{ vm_memory_high_watermark, 0.56 }`) -- `1073741824` is treated as an absolute number of bytes (`{ vm_memory_high_watermark, { absolute, 1073741824 } }`) -- `1024MiB` is treated as an absolute number of bytes with a unit (`{ vm_memory_high_watermark, { absolute, "1024MiB" } }`) - -The main behavioral difference is in how percentages are handled. If the current container has a memory limit (`--memory`/`-m`), a percentage value will be calculated to an absolute byte value based on the memory limit, rather than being passed to RabbitMQ as-is. For example, a container run with `--memory 2048m` (and the implied upstream-default `RABBITMQ_VM_MEMORY_HIGH_WATERMARK` of `40%`) will set the effective limit to `819MB` (which is `40%` of `2048MB`). - -### Erlang Cookie +### Environment Variables -See the [RabbitMQ "Clustering Guide"](https://www.rabbitmq.com/clustering.html#erlang-cookie) for more information about cookies and why they're necessary. +For a list of environment variables supported by RabbitMQ itself, see the [Environment Variables section of rabbitmq.com/configure](https://www.rabbitmq.com/configure.html#supported-environment-variables) -For setting a consistent cookie (especially useful for clustering but also for remote/cross-container administration via `rabbitmqctl`), use `RABBITMQ_ERLANG_COOKIE`: +**WARNING:** As of RabbitMQ 3.9, all of the docker-specific variables listed below are deprecated and no longer used. Please use a configuration file instead; visit [rabbitmq.com/configure](https://www.rabbitmq.com/configure.html) to learn more about the configuration file. For a starting point, the 3.8 images will print out the config file it generated from supplied environment variables. -```console -$ docker run -d --hostname some-rabbit --name some-rabbit --network some-network -e RABBITMQ_ERLANG_COOKIE='secret cookie here' %%IMAGE%%:3 +```bash +# Unavailable in 3.9 and up +RABBITMQ_DEFAULT_PASS +RABBITMQ_DEFAULT_PASS_FILE +RABBITMQ_DEFAULT_USER +RABBITMQ_DEFAULT_USER_FILE +RABBITMQ_DEFAULT_VHOST +RABBITMQ_ERLANG_COOKIE +RABBITMQ_MANAGEMENT_SSL_CACERTFILE +RABBITMQ_MANAGEMENT_SSL_CERTFILE +RABBITMQ_MANAGEMENT_SSL_DEPTH +RABBITMQ_MANAGEMENT_SSL_FAIL_IF_NO_PEER_CERT +RABBITMQ_MANAGEMENT_SSL_KEYFILE +RABBITMQ_MANAGEMENT_SSL_VERIFY +RABBITMQ_SSL_CACERTFILE +RABBITMQ_SSL_CERTFILE +RABBITMQ_SSL_DEPTH +RABBITMQ_SSL_FAIL_IF_NO_PEER_CERT +RABBITMQ_SSL_KEYFILE +RABBITMQ_SSL_VERIFY +RABBITMQ_VM_MEMORY_HIGH_WATERMARK ``` -This can then be used from a separate instance to connect: +### Memory Limits -```console -$ docker run -it --rm --network some-network -e RABBITMQ_ERLANG_COOKIE='secret cookie here' %%IMAGE%%:3 bash -root@f2a2d3d27c75:/# rabbitmqctl -n rabbit@some-rabbit list_users -Listing users ... -guest [administrator] -``` +RabbitMQ contains functionality which explicitly tracks and manages memory usage, and thus needs to be made aware of cgroup-imposed limits (e.g. [`docker run --memory=..`](https://docs.docker.com/config/containers/resource_constraints/#limit-a-containers-access-to-memory)). -Alternatively, one can also use `RABBITMQ_NODENAME` to make repeated `rabbitmqctl` invocations simpler: +The upstream configuration setting for this is `vm_memory_high_watermark` in `rabbitmq.conf`, and it is described under ["Memory Alarms"](https://www.rabbitmq.com/memory.html) in the documentation. If you set a relative limit via `vm_memory_high_watermark.relative`, then RabbitMQ will calculate its limits based on the host's total memory and not the limit set by the contianer runtime. -```console -$ docker run -it --rm --network some-network -e RABBITMQ_ERLANG_COOKIE='secret cookie here' -e RABBITMQ_NODENAME=rabbit@some-rabbit %%IMAGE%%:3 bash -root@f2a2d3d27c75:/# rabbitmqctl list_users -Listing users ... -guest [administrator] -``` +### Erlang Cookie + +See the [RabbitMQ "Clustering Guide"](https://www.rabbitmq.com/clustering.html#erlang-cookie) for more information about cookies and why they're necessary. For setting a consistent cookie (especially useful for clustering but also for remote/cross-container administration via `rabbitmqctl`), provide a cookie file (default location of `/var/lib/rabbitmq/.erlang.cookie`). -If you wish to provide the cookie via a file (such as with [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/)), it needs to be mounted at `/var/lib/rabbitmq/.erlang.cookie`: +For example, you can provide the cookie via a file (such as with [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/)): ```console docker service create ... --secret source=my-erlang-cookie,target=/var/lib/rabbitmq/.erlang.cookie ... %%IMAGE%% @@ -96,70 +92,12 @@ $ docker run -d --hostname my-rabbit --name some-rabbit -p 8080:15672 %%IMAGE%%: You can then go to `http://localhost:8080` or `http://host-ip:8080` in a browser. -### Environment Variables - -A small selection of the possible environment variables are defined in the Dockerfile to be passed through the docker engine (listed below). For a list of environment variables supported by RabbitMQ itself, see: https://www.rabbitmq.com/configure.html - -For SSL configuration without the management plugin: - -```bash -RABBITMQ_SSL_CACERTFILE -RABBITMQ_SSL_CERTFILE -RABBITMQ_SSL_DEPTH -RABBITMQ_SSL_FAIL_IF_NO_PEER_CERT -RABBITMQ_SSL_KEYFILE -RABBITMQ_SSL_VERIFY -``` - -For SSL configuration using the management plugin: - -```bash -RABBITMQ_MANAGEMENT_SSL_CACERTFILE -RABBITMQ_MANAGEMENT_SSL_CERTFILE -RABBITMQ_MANAGEMENT_SSL_DEPTH -RABBITMQ_MANAGEMENT_SSL_FAIL_IF_NO_PEER_CERT -RABBITMQ_MANAGEMENT_SSL_KEYFILE -RABBITMQ_MANAGEMENT_SSL_VERIFY -``` - -### Setting default user and password - -If you wish to change the default username and password of `guest` / `guest`, you can do so with the `RABBITMQ_DEFAULT_USER` and `RABBITMQ_DEFAULT_PASS` environmental variables: - -```console -$ docker run -d --hostname my-rabbit --name some-rabbit -e RABBITMQ_DEFAULT_USER=user -e RABBITMQ_DEFAULT_PASS=password %%IMAGE%%:3-management -``` - -You can then go to `http://localhost:8080` or `http://host-ip:8080` in a browser and use `user`/`password` to gain access to the management console - -To source the username and password from files instead of environment variables, add a `_FILE` suffix to the environment variable names (for example, `RABBITMQ_DEFAULT_USER_FILE=/run/secrets/xxx` to use [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/)). - -### Setting default vhost - -If you wish to change the default vhost, you can do so with the `RABBITMQ_DEFAULT_VHOST` environmental variables: - -```console -$ docker run -d --hostname my-rabbit --name some-rabbit -e RABBITMQ_DEFAULT_VHOST=my_vhost %%IMAGE%%:3-management -``` - -### Enabling HiPE (deprecated) - -**Note**: HiPE is disabled since version 3.7.15 of rabbimq images (https://github.com/docker-library/rabbitmq/pull/340) - -See the [RabbitMQ "Configuration"](http://www.rabbitmq.com/configure.html#config-items) for more information about various configuration options. - -For enabling the HiPE compiler on startup use `RABBITMQ_HIPE_COMPILE` set to `1`. According to the official documentation: - -> Set to true to precompile parts of RabbitMQ with HiPE, a just-in-time compiler for Erlang. This will increase server throughput at the cost of increased startup time. You might see 20-50% better performance at the cost of a few minutes delay at startup. - -It is therefore important to take that startup delay into consideration when configuring health checks, automated clustering etc. - ### Enabling Plugins Creating a Dockerfile will have them enabled at runtime. To see the full list of plugins present on the image `rabbitmq-plugins list` ```Dockerfile -FROM rabbitmq:3.7-management +FROM rabbitmq:3.8-management RUN rabbitmq-plugins enable --offline rabbitmq_mqtt rabbitmq_federation_management rabbitmq_stomp ``` @@ -173,12 +111,10 @@ Example `enabled_plugins` ### Additional Configuration -If additional configuration is required, it is recommended to supply an appropriate `/etc/rabbitmq/rabbitmq.conf` file (see [the "Configuration File(s)" section of the RabbitMQ documentation for more details](https://www.rabbitmq.com/configure.html#configuration-files)), for example via bind-mount, [Docker Configs](https://docs.docker.com/engine/swarm/configs/), or a short `Dockerfile` with a `COPY` instruction. +If configuration is required, it is recommended to supply an appropriate `/etc/rabbitmq/rabbitmq.conf` file (see [the "Configuration File(s)" section of the RabbitMQ documentation for more details](https://www.rabbitmq.com/configure.html#configuration-files)), for example via bind-mount, [Docker Configs](https://docs.docker.com/engine/swarm/configs/), or a short `Dockerfile` with a `COPY` instruction. Alternatively, it is possible to use the `RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS` environment variable, whose syntax is described [in section 7.8 ("Configuring an Application") of the Erlang OTP Design Principles User's Guide](http://erlang.org/doc/design_principles/applications.html#id81887) (the appropriate value for `-ApplName` is `-rabbit`), this method requires a slightly different reproduction of its equivalent entry in `rabbitmq.conf`. For example, configuring [`channel_max`](https://www.rabbitmq.com/configure.html#config-items) would look something like `-e RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS="-rabbit channel_max 4007"`. Where the space between the variable `channel_max` and its value `4007` correctly becomes a comma when translated in the environment. -Additional configuration keys would be specified as a list. For example, configuring both [`channel_max`](https://www.rabbitmq.com/configure.html#config-items) and [`auth_backends`](https://www.rabbitmq.com/ldap.html#overview) would look something like `-e RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS="-rabbit channel_max 4007 auth_backends [rabbit_auth_backend_ldap,rabbit_auth_backend_internal]"`. Note that some variables such as for `auth_backends` require their value(s) to be enclosed in brackets, and for multiple values explicitly including the comma as a delimiter. - ### Health/Liveness/Readiness Checking See [the "Official Images" FAQ](https://github.com/docker-library/faq#healthcheck) and [the discussion on docker-library/rabbitmq#174 (especially the large comment by Michael Klishin from RabbitMQ upstream)](https://github.com/docker-library/rabbitmq/pull/174#issuecomment-452002696) for a detailed explanation of why this image does not come with a default `HEALTHCHECK` defined, and for suggestions for implementing your own health/liveness/readiness checks.