Setting Up Containers on Ubuntu 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 Ubuntu instance in Amazon 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 Ubuntu 16.04 host, Ubuntu 16.04 LTS – Xenial (HVM) is recommended.
    • For an Ubuntu 14.04 host, Ubuntu Server 14.04 LTS (HVM) 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 Ubuntu host. Instructions can be found on the Docker Get Docker for Ubuntu Web page.

Step 3: Set Storage-Driver and IPtables

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

Systemd-Based Ubuntu 16.04 Systems

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

Upstart-Based Ubuntu 14.04 Systems

For an upstart-based Ubuntu 14.04 system, add a line to /etc/default/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.

DOCKER_OPTS="--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.

Systemd-Based Ubuntu 16.04 Systems

  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

Upstart-Based Ubuntu 14.04 Systems

  1. For Ubuntu 14.04, the privileged option must be set to true.

    The docker-create file for test deployments will be similar to this:

    >sudo tee /root/docker-create <<-EOF
    #!/bin/bash
    sudo docker create \
    --privileged=true \
    --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”.

    Also, in the example, --user=1000001. It is recommended that --user=<uid> is used and that uid be set to a number greater than 1000000.

    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 Ubuntu 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.