rabbitmq/rabbitmq-website

RabbitMQ website

Website

This repository contains the source code of the RabbitMQ website, rabbitmq.com. Please make sure to read the Workflow section before contributing.

Workflow

TL;DR

Here is a summary of which version of the documentation corresponds to which branch and directory:

Version of RabbitMQ	Branch	Sub-directory	Served at
Development version	main	docs	www.rabbitmq.com/docs/next
3.13	main	versioned_docs/version-3.13	www.rabbitmq.com/docs
3.12	v3.12.x	root	v3-12.rabbitmq.com

Branches and versioning

The main branch is the production branch. Commits to it are deployed automatically to www.rabbitmq.com by a Cloudflare worker.

We keep several versions of the docs in the main branch. Docusaurus uses the following directories:

• docs contains the docs of the future version of RabbitMQ, thus it is the work in progress. It is served at https://www.rabbitmq.com/docs/next.
• versioned_docs contains one directory per version; for example, versioned_docs/version-3.13. The latest version is served at https://www.rabbitmq.com/docs. Older versions are served at …/docs/$version.

Changes should be made to docs and to any version they apply. Here is an example:

# Make changes to the future version’s docs.
$EDITOR docs/configure.md

# Test the change in a browser.
npm start

# Once happy, apply to any version you see fit.
cd versioned_docs/version-3.13
git diff ../../docs | patch -p2

# Test again in a browser.
npm start

# Commit everything.
git add docs versioned_docs
git commit

Please read the documentation of Versioning in Docusaurus to learn more.

Older versions of the docs that we don’t want to host in Docusaurus to limit the number of versions are put in branches of the form v3.13.x, v4.0.x, etc. These branches are deployed automatically too and they use domain names of the form v3-13.rabbitmq.com, v4-0.rabbitmq.com, etc. respectively. Note that these branches used as examples may not exist yet if the corresponding docs are still maintained in the main branch.

v3.12.x is a bit special in the sense that it is using the old static website generator. This one is deployed by GitHub Actions to a Cloudflare worker. It is available at https://v3-12.rabbitmq.com.

How to build

This website is built using Docusaurus 3, a modern static website generator.

Installation

You need to install JS components used by Docusaurus first:

npm install

You need to de this once only.

Local Development

The following command starts a local development server and opens up a default browser window. Most changes are reflected live without having to restart the server.

npm start

To use a different browser, for example, Brave Beta, set the BROWSER env variable when running npm start:

BROWSER="Brave Beta" npm start

Build

The following command generates static content into the build directory and can be served using any static contents hosting service.

npm run build

This is important to run this command before pushing changes to GitHub to make sure the build is successful. This is the command that will be used to deploy the website in production.

Copyright and License

© 2007-2024 Broadcom. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.

The RabbitMQ documentation is dual-licensed under the Apache License 2.0 and the Mozilla Public License 2.0. Users can choose any of these licenses according to their needs. However, the blog is excluded from this license and remains the intellectual property of Broadcom Inc. Blog posts may not be restributed.

SPDX-License-Identifier: Apache-2.0 OR MPL-2.0

rabbitmq-website's Issues

Port Python tutorials to Pika 0.10

See the announcement and related rabbitmq-tutorials issue.

Do a code review for OpenStack Oslo RabbitMQ adapter

and suggest possible points of improvement.

Filing here for the lack of a more suitable place. We want a list of specific points of improvements in the end as the outcome of this.

Update Python tutorials to be Python 2.x and 3.x compatible

We already have the code updated.

Port tutorials to amqp.node

This involves mostly creating the pages for each tutorial and doing rewording to adapt to the JS code.

Document hostname resolution requirements

We need to make it clearer what the runtime requires from hostnames (unified resolution, all short or all FQDN hostnames) as well as mention inetrc, which
can be very useful in environments where DNS and /etc/hosts cannot be modified.

This is something that I had to explain fairly frequently recently.

javascript tutorial mentions rubygems

See the teasers section here: https://github.com/rabbitmq/rabbitmq-website/blob/master/site/tutorials/tutorial-five-javascript.md

inconsistent wording between website docs and tutorials

See http://stackoverflow.com/questions/32906938/rabbitmq-acks-republishing

Improve OpenStack's documentation on RabbitMQ as needed

Filing it here for the lack of a more suitable place.

We need to review OpenStack's documentation on RabbitMQ setup and maintenance, and contribute improvements as we see fit.

Update the plugin development guide for RabbitMQ 3.6.x

Document TLS peer verification for Shovel and Federation

(the client end of the stick)

Clarify how to disable subscription TTL for the MQTT plugin

See rabbitmq/rabbitmq-mqtt#26

Add link to this repo from the rabbitmq.com webpage

We should link to this repo from the footer, and possibly add direct links from each page to their source here.

Misleading sentence

In second tutorial there is no scheduled messages in real meaning
(as https://github.com/rabbitmq/rabbitmq-delayed-message-exchange)

The main idea behind Work Queues (aka: Task Queues) is to avoid doing a resource-intensive task immediately and having to wait for it to complete. Instead we schedule the task to be done later. We encapsulate a task as a message and send it to a queue...

The link: https://www.rabbitmq.com/tutorials/tutorial-two-php.html
I can provide PR, but don't know if that is the culture here :)

update STOMP plugin docs to add x-queue-name header

check rabbitmq/rabbitmq-stomp#43

Go tutorial one mentions ruby

Search for "In this part of the tutorial we'll write two small programs in Ruby"

Update logo

Marketing and legal have asked me to update the logo.

Java Client build instruction are broken

After 0d1b2bd0e84b8f77b2f62d4ee90983458baef02d, the expected path to codegen directory changed from rabbitmq-codegen to rabbitmq_codegen. As commit message mentions erlang.mk layout, I assume that it is the docs that need updating.

Invalid ATOM news feed

See the W3C report:
http://validator.w3.org/feed/check.cgi?url=http%3A%2F%2Fwww.rabbitmq.com%2Fnews.atom

Reported by Aaron Kondziela [email protected] on the mailing-list:
https://groups.google.com/d/topic/rabbitmq-users/RuNYBYRy5EI/discussion

OSS this repo

Any reason not to?

SSL distribution: document that Erlang ignores dist. port range

We receive several reports of this problem on the mailing-list and IRC.

It seems nobody got back to @videlalvaro on the Erlang mailing-list so far, we should probably send a patch to move this forward.

Improve rabbit.auth_backends documentation

E.g. it surely should be explained well in the Access Control document. See this mailing list thread, for instance. There are similar ones, people are confused by the docs we have.

Wrong default value for 'queue_index_embed_msgs_below' in configure.xml

The default value is 4096, not 1024.

toggle teaser answers in tutorial five does not work

(Briefly) document TLS alert "bad record MAC"

{inet_error,{tls_alert,"bad record mac"}}

can have multiple underlying reasons but we should explain that it comes down to transferred data integrity.

See ruby-amqp/bunny#289.

Update client build docs

Title.

Revisit Java client user guide intro

The one we have hasn't seen an update in a while, and is anything but user-friendly. E.g. it links to documents that are of no interest to beginners, starts with explaining the nitty gritty details instead of providing an overview, and so on.

Prepare the repo for open sourcing

From legal:

1) copyright headers on all files:

Copyright (C) [START_DATE]-2015 Pivotal Software, Inc. 

All rights reserved. This program and the accompanying materials
are made available under the terms of the under the Apache License, 
Version 2.0 (the "License”); you may not use this file except in compliance 
with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

2) LICENSE and NOTICE file in top-most directory

- LICENSE should be the full text of the Apache 2.0 license 
- NOTICE should look like this:

[PRODUCT_NAME]

Copyright (c) [START_DATE]-2014 Pivotal Software, Inc. All Rights Reserved. 

This product is licensed to you under the Apache License, Version 2.0 (the "License").  
You may not use this product except in compliance with the License.  

This product may include a number of subcomponents with separate copyright notices 
and license terms. Your use of these subcomponents is subject to the terms and 
conditions of the subcomponent's license, as noted in the LICENSE file.

3) Scrub any/all comments for unnecessary content (developer communications, names, informal or internal Pivotal references, customer/competitor references, proprietary information about internal workings of Pivotal, etc) - basically, if a comment isn’t intended for a public audience it should be removed or revised.

• Add LICENSE and NOTICE files
• Add a new README without Pivotal-specific bits
• Add copyright headers
• Fix UTF-8 character rendering in Markdown
• Scrub any sensitive content if necessary
• Get legal permission to open source
• Create a new public repository and push the latest commit only to it

Mirrors & availability

Hi there!

I'm installing RabbitMQ on a somewhat regular basis through CI, and from time to time, it seems like rabbitmq.com is unavailable. While not very common, it seems to be at least a few times a year:

2015 March 4 - https://twitter.com/RabbitMQ/status/573051967846678528, travis-ci/travis-ci#3330
2015 June 17 - http://permalink.gmane.org/gmane.comp.networking.rabbitmq.general/42670
2015 September 16 - (currently down)

Is there a better mirror to download packages from? Or anything I can do to help? Cheers!

incomplete sentence on MQTT guide

See: 8ed285f#diff-387006dd1dc958eefef1e5c3257b102cR29

.NET client tutorials should use named arguments everywhere

As one can see in tutorial 1, our tutorials use named arguments in some places but not everywhere. We should do that across the board as it makes the code a lot clearer to beginners.

Add link to this repo from the rabbitmq.com webpage

We should link to this repo from the footer, and possibly add direct links from each page to their source here.

Clarify how to use queue arguments with STOMP

fix typo in the "Hello World!" java tutorial

https://groups.google.com/forum/#!topic/rabbitmq-users/7N4KgPVerhc

Make it clear that MQTT plugin targets 3.1.1 now

Custom search on rabbitmq.com returns no results

I've tried using a couple of obvious searches such as "queue" and "channel" and I'm not getting any results.
Tried in Chrome and Firefox, same result.

Mentioned this on the rabbitmq-users mail list and was told it was a known issue and to create a ticket here.

Update community plugins page to reflect various plugins moving from my github to rabbitmq's

I just moved rabbitmq-auth-backend-http, rabbitmq-auth-backend-amqp, rabbitmq-management-themes, rabbitmq-top, rabbitmq-event-exchange, rabbitmq-management-exchange and rabbitmq-lvc-plugin from my personal github to the rabbitmq organisation. community-plugins.xml needs to reflect that change, as does the build script.

Note that rabbitmq-management-themes is not currently in the community plugins, since I originally wrote it for a joke. But it is possibly useful enough to put there.

Document how to limit TLS connections to specific ciphers

Properly document DefaultBasicConsumer

Currently the docs recommend QueueingBasicConsumer, which is no longer relevant in 3.5.0 due to concurrent dispatch used by channels. It also cannot be recovered by automatic recovery and is error prone.

It's a real shame we are in this situation with the .NET guide.

update PHP examples to latest version of php-amqplib

Switch .NET tutorials away from QueueingBasicConsumer

See rabbitmq/rabbitmq-tutorials#58.

Fix paragraph about branches on GitHub

The website still mentions issueNNNNN.

Javascript tutorial 3 mentions .rb files

search for "creates bindings and queues as we want. With two receive_logs.rb"

Missing requirements in Server Build Instructions

http://www.rabbitmq.com/build-server.html is missing zip and unzip as a requirement.

Also the requirement for Python 2 is not stated while Python 3 is unsupported.

Mirrors for build artifacts

Our current hosting provider (which shall remain unnamed, but they claim to be a market leader in what they do) has been going from downtime to planned maintenance that lasts "several days".

We should abandon all hope that it's going to get better and move at least build artifacts to AWS.

Switch Java tutorials away from QueueingConsumer

See rabbitmq/rabbitmq-tutorials#58. The same applies to Java.

Link to rabbitmq-codegen repository are broken

Because link written into /site/java-client.xml line 168 end with an unwanted /, created links are broken.

• Wrong web page https://www.rabbitmq.com/java-client.html
  • Actually: git clone https://github.com/rabbitmq/rabbitmq-codegen/.git
  • Good one: git clone https://github.com/rabbitmq/rabbitmq-codegen.git

Mention client [un]awareness of cluster topology

See this mailing list thread.

Port tutorials to golang

Clarify that queue mirroring is CP in the docs

It says that we are able to choose consistency and availability from the CAP theorem [1].

Looks like it's not true according to the following answer.
https://www.quora.com/Whats-the-difference-between-CA-and-CP-systems-in-the-context-of-CAP-Consistency-Availability-and-Partition-Tolerance
"The CAP theorem is woefully badly stated. It's not usefully about a straight choice between C, A and P - it is actually about what you give up if you have a partition. "

[1] https://www.rabbitmq.com/distributed.html

Add an OpenStack guide

Similar to the one we have for EC2.