The Long-Winded Guide to setting up Amlen: Installation

This is the Installation section of a multi-part guide to setting up the Amlen Message Broker. If you want to see the other parts check out the Introduction/Contents.

So, on with the show:

Where to install Amlen?

Amlen is installed on top of Linux – currently RHEL8 (including clones like AlmaLinux 8), RHEL7 (incl clones) and Fedora 34. A common question is whether virtual machines, containers, kubernetes, OpenShift should be used.

Amlen comes as rpms, but it also includes an example Dockerfile so that a container can easily be built. Amlen is often in Kubernetes/OpenShift environments – complicated a little because it is usually stateful. There are often durable subscriptions and buffered messages or even just configuration so stateful sets and persistent volumes are usually needed. This make use in Kubernetes tricker than an entirely stateless piece of software; as a project we need to make use in Kubernetes easier and help manage upgrades etc with a Kubernetes operator but even though such an operator doesn’t exist many customers already choose Kubernetes based environments.

How big?

The server needs enough memory to hold all the messages it will buffer in memory – when the memory available in the system is 85% used it will prevent new publications. For a very small system, 4GiB of RAM may be enough. We suggest a very rough rule of thumb of 4000 connections for each GiB of RAM but this depends on the use case and many messages will be buffered per client.

However much RAM is selected, disk space of at least 4x the amount of RAM needs to be available under /var/lib/store as this is where messages are persisted to and compressed etc.

If you have a large system but want to restrict Amlen to use only a small fraction of the memory/disk space then run the server inside a container with a memory limit – you can also limit the number of CPUs to use.

Installing and starting the Server and WebUI

We’ll use the RPMs directly (check out the documentation if you want to build a container).

  1. Download the tar.gz archives that correspond to the Server and WebUI
  2. Extract the rpms out of the archives
  3. Install both the server and webui rpms in the normal way for the OS you’re using e.g. on AlmaLinux8:
    sudo dnf install <path>/EclipseAmlenServer*rpm
    sudo dnf install <path>/EclipseAmlenWebUI*rpm
  4. Start both the Server and the WebUI (here we put them on the same system but they can be installed separately on different systems):
    sudo systemctl start imaserver
    sudo systemctl start imawebui

Connecting the WebUI to the Server

We’ll need access to port 9089 on the system running the server and 9087 on the system running the WebUI.
We’ll need a browser that has access to those ports on the system in question and using that browser visit:
https://<host or IP address for server>:9089/
(accepting the scary warnings about self-signed certificates), you should see an ‘About’ page saying that you have reach the Amlen Server.

Then visit the WebUI:
https://<host or IP address for WebUI:9087/
Once the warnings about self-signed certificates are accepted, you should be presented with a login page. We haven’t changed the passwords yet so login in with user: admin and password: admin

You should then be presented with a dialogue box to configure connecting the WebUI to the server. Test the connection – as long as you’ve already accepted the server certificate it should work – save the connection and we have the server and WebUI running together.


Initial Configuration

We start by setting up passwords to access both the WebUI and the server.

We first set the the password for the admin super user for the server:

  1. In the WebUI, visit: Server>Admin Endpoint
  2. Change User Id to: ima-admin
  3. Change Password to: fish7lettuce!
  4. Make the admin endpoint require a password by:
    1. Go to: Server>Security Settings.
    2. In Security Profiles section, click on ‘AdminDefaultSecProfile’,
    3. Click on the pencil icon
    4. Tick the “Use Password Authentication” check-box and click ‘save’. When prompted enter the user id and password we set (in steps 2 & 3) and then reload the page.

To set the WebUI Password:

  1. In the WebUI, Chose “WebUI > WebUI Users”.
  2. Click on admin
  3. Choose “Other Actions > Reset Password”
  4. Set the password to something. In this guide we’ll assume it is set to: light4scale!

Now we have set up the passwords, let’s prove they are needed to access the REST interface – this also demonstrates using the curl command to access the interface.

Log into the system where you install the server then try and issue admin commands without a password:
export IMA_ADMIN=https://127.0.0.1:9089/ima/v1
curl -X GET http://$IMA_ADMIN/ima/v1/service/status/Server
You should see an error. Now if we use a password:
export IMA_USER=”admin:fish7lettuce!”
curl -u $IMA_USER -X GET http://$IMA_ADMIN/ima/v1/service/status/Server

You should see the status of the server.

Connecting our first client

Now we have the server and the WebUI running, we are going to connect our first client. We’re going to (temporarily) create an MQTT service without TLS and authenticatuion

  1. In the WebUI, Go to Messaging > Message Hubs
  2. Click on “DemoHub” and click the pencil icon, then the “Endpoints” tab. Select the “DemoMqttEndpoint and click the pencil icon.
  3. Change the Port to be 1889, ticked the “Enabled” checkbox and then “Save” – we’re open for business!

Now we need an MQTT client. If your server can receive connections from the open internet to your server you can use a javascript client (http rather than https is important in the address as the server doesn’t have TLS set up yet):
http://amlen.org/samples/MQTTClient/
(set the host to be the IP address of the server, change the port to 1889 and click Connect – you can now publish and subscribe)

If your server is not exposed to the internet, then you need an MQTT client somewhere that can access the server. I tend to use the Paho Python MQTT client for quick tests. Once you have the Paho Python client you can test your server by using the samples that come with it e.g. subscribing:
python3 client_sub_opts.py -H <server IP> -P 1889 -t ‘topic1/#’

and then with the subscriber running, in a different terminal publish some messages:
python3 client_pub_opts.py -H <server IP> -P 1889 -t /topic1/subtopic1 -N 10 -D

You should see the subscriber receive 10 messages (because of the -N 10 in the arguments to the publisher app).

So far we have the server up and running but we have no TLS encryption and we can fix that in the next installment.

Leave a comment

Your email address will not be published.