Skip to content

Home

Jump to bottom
Rajeev R edited this page Oct 7, 2019 · 144 revisions

Overview

This page describes the steps required for installing the Jazz framework, using the Jazz Installer. For more details on the Jazz Serverless Development Framework, please refer here.

Prerequisites

  • Installer box: Installer box that brings up the Jazz stack.

    • You can use a CentOS (7.x) or Ubuntu18 instance as your installer box. To create a new CentOS/Ubuntu instance please refer here.
    • You can use local machines with CentOS (7.x) or Ubuntu18

  • AWS account: Installation will deploy the platform components as well as create user services in AWS.

Ensure you have the IAM keys with sufficient permissions to create the following AWS resources in us-east-1/us-west-2:

AWS::ApiGateway
AWS::CloudFormation
AWS::CloudFront
AWS::Cognito
AWS::DynamoDB    
AWS::ECS
AWS::Elasticsearch
AWS::IAM::Policy
AWS::Kinesis
AWS::Lambda
AWS::S3::Bucket
AWS::Cloudwatch
AWS::RDS
AWS::ELB

Note that not all AWS regions support all of these AWS resources yet, and if you pick a region that lacks support for one or more of these resource types, the installer will fail. Refer to the AWS offical region table for an up-to-date listing. The installer has been tested in the following regions:

  • us-east-1
  • us-west-2

A list of the resources the Terraform installer will create can be found here, though running terraform plan will provide a more detailed and accurate listing.

Scenarios

Install

  • Ensure that you have a standard install of Python 3.6 or greater, with pip and setuptools

NOTE: If you want to use the SCM(Gitlab) and CI system(Jenkins) instances the installer sets up for you, then no additional steps are required. If you wish to "bring your own" SCM and CI instances, please verify you have completed all the Additional Prerequisites for Existing Instances steps first.

  1. If have not already SSH'ed into to the installer box that you set up here, do so. (a). (Optional) Export your AWSCLI credentials as environment variables if you have not already done so. If the credentials are not detected in the environment you will be asked for them later:

    export AWS_ACCESS_KEY_ID=<YOUR_ACCESS_KEY>
export AWS_SECRET_ACCESS_KEY=<YOUR_SECRET_KEY>

  2. Run the below commands to start the installation. This will set up a Python3 virtual env and install the required packages.

    git clone https://github.com/tmobile/jazz-installer.git
cd jazz-installer
python3 -m virtualenv env && source env/bin/activate
pip install -r requirements.txt
python Installer.py install --stackprefix myteststack --adminemail test@tst.com --region us-east-1 scenario3

    • NOTE: If you are looking to enable optional features like code quality, use the command listed here.

    • NOTE: If you want to install a specific version of Jazz, or the latest develop version, simply:

      1. Clone the correct installer branch (e.g. for version 1.7): git clone --branch 1.7 https://github.com/tmobile/jazz-installer.git
      2. Instruct the installer script to use the matching branch when installing the Jazz core: python Installer.py install --branch 1.7 <other_args> scenario3

  3. You will then be prompted to input any required installer values. Note that all installer values can also be supplied as command line flags, to see the list of flags/options use the help flag for the option you need more information about, e.g. python Installer.py install --help or python Installer.py install scenario3 --help * At a minimum, you will be asked to provide a prefix for your stack, as well as an admin email address that will be used to manage Jazz * DO NOT run the installer on top of an existing installation without first destroying the existing installation (python Installer.py uninstall).

  4. Once the installation is complete, you should see a log similar to this:

    Please use the following values for checking out Jazz
 ________________________________________________
{
     "Jenkins ELB" : "{Jenkins Host Name}",
     "Jenkins Username" : "{Jenkins User Name}",
     "Jenkins Password" : "{Jenkins Password}",
     "Jazz Home" : "{Jazz Home Page}",
     "Jazz Admin Username" : "{Jazz Admin Email Address you provided}",
     "Jazz Admin Password" : "{Jazz Admin Password that was autogenerated for you}",
     ...
}

    You can also run cat stack_details.json inside the jazz-installer directory to see the above information for using your Jazz install at any time.

  5. Follow the post-install steps covered here before starting to use Jazz.

Limitations

  • Current version runs only on AWS Stack.
  • From Jazz version > v1.12, installer deploys docker containers (related to internal Jazz components) to ECS Fargate service. Currently, Fargate tasks only support nonpersistent storage volumes as described here. AWS is working on related features according to their roadmap. We'll implement changes that can potentially resolve these limitations as soon as related features are available in AWS Fargate.
Clone this wiki locally