Demo Install

Overview

The herd team created an AWS CloudFormation template in order to make it super-easy to start a demo environment. Please be aware that although there is no additional charge for AWS CloudFormation, you still may pay for the AWS resources that are created (e.g., Amazon EC2 and RDS instances). The template will perform these steps:

• Create EC2 instance with Tomcat and Postgres
• Create herd schema in the Postgres DB and populate basic configuration data and example reference data
• Deploy herd war to Tomcat
• Create necessary AWS security groups and roles
• Launch the herd instance

Pre-requisites

Basic knowledge of AWS is required, for example creation and management of EC2 and S3 resources and Security Groups.

Instructions

In order to create a new stack containing Herd application, perform the following steps:

1. Download the herd AWS CloudFormation template to your computer
2. Login to your AWS Console and click on CloudFormation service.
3. Select 'Create New Stack' and browse for the previously downloaded template. Click Next.
4. The next screen allows you to enter the name of your Stack and presents a list of parameters. All parameters have default values which are fine to configure and start a demo instance, except for the KeyName.
5. Please specify name of the key which you have in your AWS account, so you can later ssh to the herd application server. This is not required for the demo to start, but is quite useful if you later would want to modify something.
6. Click 'Next' and optionally tag resources in herd stack. This allows you to distinguish resources created by this template.
7. On the last page acknowledge that stack will create IAM resources and click 'Create'.

Stack creation will take approximately 5 minutes depending on the region load. When stack reaches "CREATE_COMPLETE" state, please examine 'Output tab' and find the IP address of newly-created herd application server, URLs for build info, REST API documentation and UI.

Note you can currently only start the stack in "us-east-1" region.

Using the Demo

The best way to continue learning is to go through our Quick Start to Registering Data tutorial. This has explanations and examples that will help you understand some of the first tasks you should perform with herd. For more broad exploration, check out the REST API documentation link in the output of your stack - each REST service has a brief explanation, example requests and responses, and a 'Try It' link to exercise the service in the demo environment.

Authentication and Authorization controls in Herd

Herd has a configurable method of interfacing with external authentication providers. This relies on the external authentication mechanism creating HTTP headers for authenticated users. Several values in the (Configuration Values)[https://github.com/FINRAOS/herd/wiki/configuration-values] table control integration with external authentication providers:

• security.enabled.spel.expression - a logical expression to control whether or not security is enabled
• security.http.header.implementation - a boolean for whether or not Herd will look for authentication headers
• security.http.header.names - configurable list of what HTTP headers map to certain required fields for Herd security
• security.http.header.role.regex - the regular expression used to parse out roles from specific HTTP header

The authentication information can then be used to control authorization at two levels as described in the section below.

Service-level authorization (available starting with release 0.1.0)

Each Herd service is mapped to one or more Roles in a database table in the Herd schema. This data must be updated

Namespace-level authorization (available in future release, estimated 0.15.0)

Shutting down the Demo Stack

When you are done with it, you can shutdown and delete stack using same AWS CloudFormation page. Select the stack and click Delete.