LavinMQ LavinMQ logo
LavinMQ logo
Home Documentation Community Blog
Get started
GitHub Repository

LavinMQ installtion guide

Latest stable version: v1.0.0-beta.12

Check out the changelog for an overview of releases.

How to build LavinMQ from GitHub

LavinMQ is written in the Crystal programming language. It needs Crystal installed to compile.

To build LavinMQ you must first install Crystal. This can be done for a number of platforms by following the instructions on the Crystal site.

Once Crystal is installed you can clone the repo from GitHub and build it with

shards build --release --production
git clone git@github.com:cloudamqp/lavinmq.git
cd lavinmq
shards build --release --production
install bin/lavinmq /usr/local/bin/lavinmq

Now, LavinMQ is ready to be used. You can check the version with:

lavinmq -v

# 1.0.0-alpha.23-20-g41b81465

Installing LavinMQ on Ubuntu

LavinMQ is a modern message broker that uses the AMQP protocol. It is written in the Crystal programming language. Installation in Ubuntu is a one-step process using Ubuntu’s package manager APT.

System Requirements

LavinMQ is supported on Ubuntu 18.04 and 20.04. Supported processors include ARM, x86_64, and amd64. We recommend using xfs file systems, but ext4 is also supported.

Installation process

LavinMQ releases are hosted in packagecloud. First, you will need a key to access the repository. Evaluate the following commands in a terminal:

curl -L https://packagecloud.io/cloudamqp/lavinmq/gpgkey | sudo apt-key add -
echo "deb https://packagecloud.io/cloudamqp/lavinmq/ubuntu/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/lavinmq.list

Now, LavinMQ is ready to be installed. Evaluate the following inputs in a terminal:

sudo apt update
sudo apt install lavinmq

Configuration

After LavinMQ has been installed, it will be running as a service. The ports needed for LavinMQ are 5671 (amqp with TLS), 5672 (amqp), and 15672 (management interface).

Stopping/starting/restarting can be done by using Ubuntu’s service command. For example, to restart the service evaluate this:

service lavinmq restart

The default user for LavinMQ has the username guest with a password set to guest. This user can be deleted using the lavinmqctl CLI or by using the management interface. Additional users can be added in the same way.

Additional configuration settings can be changed in the LavinMQ configuration file, which will be installed in /etc/lavinmq for Ubuntu machines.

Install LavinMQ on MacOS

OS X users can install LavinMQ with brew:

brew install cloudamqp/cloudamqp/lavinmq

Community and contribution to LavinMQ

GitHub Discussions

Welcome to GitHub Discussions where fellow LavinMQ users exchange and discuss information. This is where we will share valuable resources, learn features and functions, and, most importantly, get help and advice from others.

Issues or Bug Reports

Have a problem or a question? You probably aren’t the first one! Search the GitHub Discussions archive and known issues on GitHub for the same or similar issues to gain advice from fellow users.

Contributions

Contributing to the LavinMQ community is a rewarding way to share information, build experience, and learn new skills. The GitHub repository can be found here:

More information about a contribution to LavinMQ can be found here.

LavinMQ Management Interface

The LavinMQ Management interface is a user-friendly dashboard to monitor and handle the LavinMQ broker from a web browser. Elements such as queues, connections, channels, exchanges, users, and user permissions can be created, deleted, and listed in the browser. The management interface also performs other important tasks such as keeping track of the number of messages in the queues and monitoring the message rate.

The LavinMQ Management Interface can be accessed using a Web browser at http://localhost:15672 if running it locally, or https://{hostname}.amq.cloudamqp.com if hosted by CloudAMQP.

LavinMQ Management Interface

AMQP Concepts

AMQP has some concepts to get familiar with. The documentation page features a complete guide to AMQP.

  • Queue - A queue is a buffer that stores messages for consumers to retrieve. A queue is bound to one or more exchanges, occasionally with a routing key. A queue may have one or many consumers.
  • Message - A message is what is transported between the publisher and the consumer, it’s essentially a byte array with some headers on top.
  • Exchange - Receives messages from producers and delivers them to queues depending on rules defined by the exchange type. In order to receive messages, a queue needs to be bound to at least one exchange.
  • Binding - AMQP allows you to very granularly route your messages between incoming exchanges and outgoing queues. A binding is a link between a queue and an exchange and is what determines to which queues a message should be routed; it may be to zero or many. How a message is routed depends on which kind of exchange the message was destined for and the “routing key”.
  • The “default exchange” - The default exchange has no name, but there’s a default binding that says that the message will arrive at a queue with the same name as the routing key.
  • Routing key - Part of the header of every message, the routing key is used to route the message.

Exchange types

Instead of publishing messages directly to a queue, the producer sends them through an exchange. An exchange is responsible for routing the messages to different queues with the help of bindings and routing keys. Bindings link queues and exchanges and routing keys are an attribute in the actual message that the exchange looks at when routing it to the proper queue.

A complete guide about the different exchange types can be found in the documentation about exchanges and bindings.

There are four exchange types:

  • Direct - A client sends a message to a queue intended for a particular recipient. The default exchange is a direct exchange with no name (empty string) pre-declared by the broker.
  • Fanout - A fanout exchange copies the message and routes it to all queues that are bound to it; the routing key is ignored.
  • Topic - A message is sent to a number of queues based on a set of rules.
  • Headers - Messages are routed based on the information contained in the headers.