CentOS on AWS

In this section we walk you through the steps to manually get a basic messaging configuration of the Solace PubSub+ software event broker Docker container up-and-running on a CentOS instance in AWS Elastic Compute Cloud (EC2).

Before you begin

It's assumed you have:

  • An Amazon EC2 account.
  • A stable version of Docker Engine installed.

System Requirements

The number of CPUs and system memory required by your event broker depends on the number of client connections you need to support. By default, fresh installations of the event broker allow up to 100 client connections by default.

To achieve desired stability and performance, the infrastructure hosting the PubSub+ Software Event Broker must provide a minimum set of system resources. System resources can be broadly categorized into requirements related to processors, memory, and storage. For details about the type of system resources required and their characteristics, see System Resource Requirements.

You can increase certain system limits using System Scaling Parameters. Increasing these system limits also increases the system resources that are required. For more information, see Modifying System Limits Using System Scaling Parameters.

Information about configuring storage can be found at Managing Storage for Container Images.

The example shown on this page is suitable for use for up to 1,000 connections, and is appropriately configured for testing and PoC activities. If you plan to use your event broker in a production environment, or scale your system above 1,000 connections, ensure that you consult the sections listed above and provision your system appropriately.

Step 1: Launch a Host & Install Docker

Use the AWS EC2 Dashboard’s Launch Instance wizard to create an Amazon Machine Image that you can use to run an event broker.

  1. On the main page of the EC2 Dashboard, select the Launch Instance button.

    Create AWS Instance

    Follow the setup wizard, and accept the recommended default settings except as noted in the following steps.

  2. In the Choose AMI step, choose an Amazon Machine Image (AMI) from the AWS Marketplace for the host:

    For example, for a CentOS 7 host, CentOS 7 (x86_64) – with Updates HVM can be used.

  3. In the Choose an Instance Type step, select an Instance Type based on the maximum number of client connections listed in the System Requirements section.
  4. In the Configure Instance Details step, set Subnet to your availability zone.
  5. In the Add Storage step, set the instance’s storage size and volume type.

    The amount of storage to attach to the instance depends on your application. Both SSD volume types, General Purpose and Provisioned IOPS, are supported.

    For test deployments, a minimum of 30 GB and Provisioned IOPS SSD are recommended.

  6. In the Tags step, assign a name to your instance.

    You can add as many tags as required by your application.

  7. At a minimum, it is recommended that the security group include the following inbound rules.
    TypeProtocolPort RangeSource
    Custom TCP RuleTCP80800.0.0.0/0
    Custom TCP RuleTCP555550.0.0.0/0
    SSHTCP220.0.0.0/0

    These port numbers are used for the following services: 22-Host SSH; 8080-SEMP /.PubSub+ Broker Manager / SolAdmin; 55555-SMF/non-compressed message data connections. Other ports can be opened as required. For a list of ports associated with event broker services, see Default Configuration for Software Event Brokers.

  8. Once you have completed the launch wizard steps, and have logged into your host, go ahead with installing and configuring Docker. Instructions can be found on the Docker Get Docker for CentOS Web page.
  9. You should note that If you are using a t2.medium instance type, a swap file must be created once the host is up-and-running. Follow these instructions:

    >sudo mkdir /var/lib/solace
    >sudo dd if=/dev/zero of=/var/lib/solace/swap count=2048 bs=1MiB
    >sudo mkswap -f /var/lib/solace/swap
    >sudo chmod 0600 /var/lib/solace/swap
    >sudo swapon -f /var/lib/solace/swap
    >sudo grep -q 'solace\/swap' /etc/fstab || sudo sh -c 'echo "/var/lib/solace/swap none swap sw 0 0" >> /etc/fstab'

Step 2: Set Storage-Driver & IPtables

You have to set the storage-driver and iptables options on the host system.

For systemd-based systems, create a daemon.json file to set the iptables and devicemapper Docker daemon options. For test deployments, it is recommended to set iptables to false and storage-driver to devicemapper. These options are set in the daemon.json file located in /etc/docker/. Follow these steps to set the options.

  1. If Docker is not stopped, then enter this command.
    >sudo systemctl stop docker
  2. Create the daemon.json file in /etc/docker/.
    sudo tee /etc/docker/daemon.json <<-EOF
    {
    "storage-driver": "devicemapper",
    "iptables": false
    }
    EOF
  3. Apply the settings.
    >sudo systemctl daemon-reload
    >sudo systemctl disable docker
    >sudo systemctl enable docker
    >sudo systemctl start docker
    

Step 3: Get a Software Event Broker

Pull the event broker image from the Docker repository using these two steps:

  1. Start Docker.

    >sudo systemctl start docker

    You can use the status command to check the status of Docker.

    >sudo systemctl status docker
  2. Pull the image:
    >sudo docker pull solace-pubsub-standard

    :  When loading is finished, you can check the image with the images command.

    >sudo docker images
    REPOSITORY                       TAG         IMAGE ID        CREATED        SIZE
    solace/solace-pubsub-standard latest b8a61124d92f 10 days ago 1.11GB

This example assumes that you are using Solace PubSub+ Standard. If you want to use another edition, you need to obtain the appropriate event broker package:

  • Solace PubSub+ Enterprise Evaluation Edition: Go to the Solace Downloads page. Then select Download in the Solace PubSub+ Enterprise Evaluation Edition Docker Images section. You will be able to download a compressed archive file called solace-pubsub-evaluation-<version>-docker.tar.gz.
  • Solace PubSub+ Enterprise: If you have purchased a Docker image of Solace PubSub+ Enterprise, Solace will give you information for how to download the compressed tar archive package from a secure Solace server. Contact Solace Support at support@solace.com if you require assistance.

Once you've obtained the package, start Docker and load the image.

For example:

>sudo docker load -i /tmp/solace-pubsub-evaluation-<version>-docker.tar.gz

Step 4: Set Docker Create Options

There are many options that you can set with the docker create command that is used to build the event broker container. In this example we will show one that sets up a simple configuration suitable for a test deployment that can be used to help you become familiar with Solace PubSub+.

  1. Create a docker-create script.
    >sudo tee /root/docker-create <<-EOF
    #!/bin/bash
    sudo docker create \
    --network=host \
    --uts=host \
    --shm-size=1g \
    --ulimit core=-1 \
    --ulimit memlock=-1 \
    --ulimit nofile=2448:42192 \
    --env 'username_admin_globalaccesslevel=admin' \
    --env 'username_admin_password=admin' \
    --name=solace <repository>:<tag>
    EOF

    For production deployments, there are use-case dependent factors that will impact the option and configuration key settings in the docker create command. For more information, see Docker Create Options and System Resource Requirements

    In this example, the admin Solace CLI user and an associated password are defined at container creation through the username_admin_globalaccesslevel and username_admin_password configuration keys. By default, in an event broker container, no Solace CLI users are defined, so setting these configuration keys allows the container to be administered through the Solace SolAdmin management tool without first entering the Solace CLI to create an admin user.

    In the above docker create command, the values of <repository> and <tag> are dependent on the event broker Docker image you previously loaded. For example, if you pulled the latest PubSub+ Standard image from Docker, the <repository> is solace/solace-pubsub-standard and the <tag> is latest. If you loaded version 8.10.0.1022 of Solace PubSub+ Evaluation Edition, the value of <repository> is solace-pubsub-evaluation and <tag> is 8.10.0.1022.

  2. Make the docker-create script executable:
    >sudo chmod +x /root/docker-create

Step 5: Create the Container

Create and run the event broker container on your host.

  1. Create the container:

    >sudo /root/docker-create

    Once it’s done running, a long identifier will be displayed that looks something like this:

    1cb8dba3c07b6970b1e22c1067fde76010259e50a8548c3f2f202a6e9ce4e345

    This is the ID for the event broker container you have just created.

  2. Start the event broker:

    >sudo docker start solace

    You can use the docker ps command to check on the status of the event broker once it’s running.

    >sudo docker ps

    The STATUS column associated with the event broker will display if the container is running and for how long.

Next Steps

You now have an event broker container with a basic configuration that is ready for messaging tasks. To get yourself going, you can access either of the Solace management tools PubSub+ Broker Manager or Solace CLI to start issuing configuration or monitoring commands.

To access Solace PubSub+ Broker Manager:

  1. Open a browser and enter http://<your-event broker's-ip-address>:8080.
  2. Log in as user admin with password admin.

To access the Solace CLI:

  1. Enter the following docker exec command:

    >sudo docker exec -it solace /usr/sw/loads/currentload/bin/cli -A

  2. Type the following commands to enter configuration mode:

    solace> enable

    solace# config

    solace(configure)#

  3. For a list of Solace CLI commands currently supported on the event broker, refer to Software Event Broker CLI Commands.