Setting Up Containers on Amazon Linux in AWS

This section will walk you through the steps required to manually get a Solace Virtual Message Router (VMR) Docker container up-and-running on an Amazon Linux Amazon Machine Image (AMI) instance in AWS Elastic Compute Cloud (EC2).

Assumptions

  • You have an Amazon EC2 account.
  • Docker Engine used—minimum version 1.12.0

Steps

Step 1: Launch a Host in AWS EC2

Use the EC2 Dashboard’s Launch Instance wizard to create an Amazon Machine Image that you can use to run a VMR Docker container on.

  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 an Amazon Linux host, Amazon Linux AMI 2016.09.1 (HVM), SDD Volume Type is recommended.

  3. In the Choose an Instance Type step, select an Instance Type.

    For a non-production deployment, the following minimum instance types are recommended:

    • To support a combined maximum of 1,000 client connections, a minimum of 2 vCPUs and 4 GiBs of memory is required. Therefore, the recommended minimum instance type is t2.medium.
    • To support a combined maximum of 10,000 client connections, a minimum of 4 vCPUs and 12 GiBs of memory is required. Therefore, the recommended minimum instance type is m4.xlarge.
    • To support a combined maximum of 100,000 client connections, a minimum of 8 vCPUs and 28 GiBs of memory is required. Therefore, the recommended minimum instance type is m4.2xlarge.

    For information about client connection scaling, refer to VMR Connection Scaling Tiers.

  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 General Purpose 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. For a test deployment, 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/SolAdmin; 55555-SMF/non-compressed message data connections. Other ports can be opened as required. For a list of ports associated with VMR services, see VMR Configuration Defaults.

  8. When using t2.medium, 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: Install Docker

Manually install and configure Docker on your Amazon Linux AMI host. Instructions can be found on the AWS Docker Basics Web page.

Step 3: Set Storage-Driver and IPtables Options

For an upstart based Amazon Linux AMI system, add a line to /etc/sysconfig/docker for setting the iptables and devicemapper Docker daemon options.

For test deployments, it is recommended to set iptables to false and the storage-driver to devicemapper. Docker should be stopped before making this change.

OPTIONS="--iptables=false --storage-driver=devicemapper"

Step 4: Get a VMR Docker Package

You must obtain a VMR Docker container image—a compressed tar archive containing a VMR Docker repository, which consists of a single VMR Docker Image.

  • Community edition of the VMR—Go to the Downloads page of dev.solace.com. Then in the VMR Community Edition area, select Docker Images > Solace VMR Docker Package. After you read and agree to the license agreement, a compressed archive file called soltr-<version>-vmr-community-docker.tar.gz will be downloaded.
  • Enterprise version of the VMR Docker package—If you have purchased an Enterprise version of the VMR Docker package, Solace will give you information for how to download an enterprise version of the compressed tar archive package from a secure Solace server. Contact Solace Support at support@solace.com if you require assistance.

Once you have obtained a copy of the Solace VMR Docker Package, you can upload it to a directory on your host and load the image using these two steps:

  1. Start Docker:

    >sudo service docker start

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

    >sudo service docker status

    The display above shows that Docker is up and running.

  2. Load the image from the VMR Docker package:

    >sudo docker load -i /tmp/soltr-<version>-vmr-community-docker.tar.gz

    In this example, it has been assumed that the compressed tar archive of an Community Edition VMR Docker container image has been uploaded to /tmp

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

    >sudo docker images

    REPOSITORY     TAG                              IMAGE ID     CREATED     SIZE
    solace-app     8.x.x.x-community               529588fc82ce 4 days ago  856.6 MB

Step 5: Set Docker Create Options

There are many options that you can set for the docker create command.

For test deployments, it is recommended that you create a docker-create file, which will enable you to set various docker create command options. The examples provided in this step will show you how to create a suitable docker-create file for a test deployment.

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 on considerations for the configuration of product deployments, see Index of VMR Container Configuration Tasks.

  1. Create a docker-create file.

    >sudo tee /root/docker-create <<-EOF
    #!/bin/bash
    sudo docker create \
    --network=host \
    --uts=host \
    --shm-size=2g \
    --ulimit core=-1 \
    --ulimit memlock=-1 \
    --ulimit nofile=2448:38048 \
    --env 'username_admin_globalaccesslevel=admin' \
    --env 'username_admin_password=admin' \
    --name=solace solace-app:<version-edition>
    EOF

    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 a VMR Docker 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 repository name is solace-app. The <version-edition> is dependent on the VMR Docker package you obtained in Step 2. For example, if you downloaded a version 8.0.0.231 Community Edition Docker Container Image, the value of <version-edition> is 8.0.0.231-community, where “version” is the release version, and the edition can be “enterprise” or “community”.

    Note: To support a combined maximum of 100,000 client connections, it is recommended to change the file descriptor setting to the following.

    --ulimit nofile=2448:1048576
  2. Make the docker-create file executable:

    >sudo chmod +x /root/docker-create

Step 6: Create the VMR Docker Container

Create and run the VMR Docker container on your Amazon Linux AMI host.

  1. Create the VMR Docker 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 VMR container you have just created.

  2. Start the VMR Docker container:

    >sudo docker start solace

    You can use the docker ps command to check on the status of the VMR Docker container once it’s running.

    >sudo docker ps

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

Additional VMR Docker Container Configuration

You now have a VMR Docker container with a basic configuration that is ready for messaging tasks. However, there are additional configuration tasks that you can perform. At this stage, you should do the following:

  1. Review the following extra configuration tasks specific to VMR Docker containers. These additional configurations allow you to further customize your VMR Docker container to better suit your particular use-case and to make it more suitable for a production deployment.

    Basic Configuration Tasks

    Below are some further configuration and monitoring tasks that are useful in the basic operation of a VMR Docker Container.

    Advanced Configuration Tasks

    Below are some common configuration tasks that often must be performed when using a VMR Docker Container in a production environment.

  2. Begin to configure and manage the VMR Docker container’s messaging operations through the Solace CLI in the same manner as you would other Solace messaging routers (say, a Solace messaging appliance or a Solace VMR machine image). For information on how to perform these configuration and management tasks, see the topics in the Router Configuration category of the Solace customer documentation.