Support and Documentation

Integrating AWS services

Many development scenarios require integrating AWS services, such as Rekognition or Translate, into the Brightspot webapp. The following sections describe how to integrate those services into Brightspot.

Integration topology

Most development scenarios involve coding on a host, building a .war, and deploying the .war to a Brightspot server running in a virtualized environment, typically a Vagrant virtual machine or a Docker container.

The most efficient way to integrate AWS into these virtualized environments is to configure the credentials on the host, and then have the virtual environment use the host's credentials.

AWS integration topology
Figure 87. AWS integration topology


Referring to the previous illustration, the host connects directly to AWS. When you run an aws command on the host:

  1. The host looks up the credentials.

  2. The host authenticates with AWS.

  3. The host sends the command to AWS.

  4. The host receives the response from AWS.

Similarly, when you run an aws command on the guest:

  1. The guest looks up the host's credentials.

  2. The guest authenticates with AWS.

  3. The guest sends the command to AWS. (The command may include some parameters retrieved from the server's context.xml configuration file.)

  4. The guest receives the response from AWS.

The advantage to this topology is that you configure the host once instead of doing the configuration on each guest.

Step 1: Configuring the host's connection to AWS

A prerequisite for this step is to open an AWS account. Amazon offers a free-tier account at AWS Free Tier. When you sign up for the account, be sure to generate an access key and a secret access key. (If you are using a shared corporate account, obtain the access key and a secret access key from the account administrator.)

Next, configure a connection from the host to an AWS service. The easiest way to ensure you have this connection is to install the AWS CLI. For information about installing the AWS CLI, see Installing the AWS CLI version 2. After you finish installing the CLI, you have two files. The first file is a credentials file.

Example 41. ~/.aws/credentials with single profile
[default]
aws_access_key_id = AASSECRETKEY
aws_secret_access_key = ASECRETACCESSKEY


Line 1 is the name of the profile. In some development environments, you may have more than one profile, such as default for your personal AWS account and corporate for your company's AWS account, as in the following example.

Example 42. ~/.aws/credentials with single profile with multiple profiles
[default]
aws_access_key_id = MYSSECRETKEY
aws_secret_access_key = MYSECRETACCESSKEY

[corporate]
aws_access_key_id = OURSSECRETKEY
aws_secret_access_key = OURSECRETACCESSKEY


The second file is a configuration file. In most cases, it specifies the AWS region serving your commands.

Example 43. ~/.aws/config
[default]
region = us-east-1


Step 2: Testing the host's connection

In this step, you test the host's connection with AWS.

aws sts get-caller-identity

This command returns your user ID, account number, and user ARN.

If you have multiple profiles, you can specify the required one at the command line.

aws sts get-caller-identity --profile=psd-corporate

As a best practice, simulate the specific calls you'll be making from Brightspot to AWS because this helps to eliminate problems at the host level when diagnosing error messages. In these commands, ensure you use the role, topic, and queue identifiers that you will configure in Brightspot.

Step 3: Integration with an individual account

This section describes how to integrate AWS services into a Vagrant virtual machine. Integration with a Docker container is similar.

Ensure the Vagrant guest can reach the ~/.aws/credentials file on the host. Vagrant provides a synchronization facility to access this file. For details, see Synced Folders.

The best approach for using the host's credentials is to assign them to AWS's environment variables on the guest as described in the following table.

Variable

Description

Example

AWS_CREDENTIAL_PROFILES_FILE

Credentials file to use when sending commands to AWS. This file resides on the host, so ensure you configure the Vagrant guest to have access to this file.

AWS_CREDENTIAL_PROFILES_FILE=/home/me/.aws/credentials

AWS_PROFILE

Profile to use when sending commands to AWS. Depending on your development environment, you can define this statically when creating the Vagrant guest, or read it from a file on the host.

AWS_PROFILE=corporate

AWS_REGION

AWS region to use. Depending on your development environment, you can define this statically when creating the Vagrant guest, or read it from ~/.aws/config on the host.

AWS_REGION=us-east-1

The aws command looks for the values of these environment variables, and reverts to default values if these variables do not exist.

Step 4: Configuring the Tomcat server

In the vast majority of production environments, media are stored on a cloud provider such as AWS. Similarly, most AWS services that you use in a development environment also require storing files in AWS buckets. For your development environment to store media on AWS buckets, you need to configure the following environment variables in Tomcat's context.xml:

  • dari/defaultStorage

  • dari/storage/some-id/bucket

  • dari/storage/some-id/class

  • dari/storage/some-id/baseUrl

  • dari/storage/some-id/secureBaseUrl

For information about configuring these environment variables, see Storage item configuration.