Introduction
The Target Experience
Step 1 - Set Up Tooling
Step 2 - Clone the AWS SaaS Boost Repository
Step 3 - Provision AWS SaaS Boost
Step 4 - Login to AWS SaaS Boost
Step 5 - Configure Application Settings
Step 6 - Upload Your Application
Step 7 - (Optional) Deploy the Sample Application
Mapping Your Application to AWS SaaS Boost
This document describes how to create and configure AWS SaaS Boost. Use this document alongside the other AWS SaaS Boost documents to get a more comprehensive view of the system.
While this document provides a review of the steps to setup AWS SaaS Boost, it is not intended to provide a deep dive into the user experience or underlying technology. These details are covered in the User Guide and Developer Guide.
Before digging into the steps needed to set up AWS SaaS Boost, let's look at the basic elements of the environment to get a better sense of what AWS SaaS Boost enables. The diagram in below shows the key components of the AWS SaaS Boost experience in the order of the setup flow. This flow presumes that you have a monolithic application -- one where your entire application (other than the database) can be packaged and deployed as a single unit.
The following is a breakdown of each of the steps:
- Set up the tooling for the install process
- Clone the AWS SaaS Boost repository
- Provision AWS SaaS Boost
- Access the AWS SaaS Boost administration web application
- Configure the application settings for your requirements
- Upload a containerized Docker image of your application to AWS SaaS Boost
At this stage, all the moving parts of the environment are now in place to begin onboarding tenants. You can use the AWS SaaS Boost application to configure and onboard new tenants, or you can make API calls from your application to trigger the onboarding of a new tenants.
The last piece to consider is the update process for your application. As changes are introduced into your application, you can upload the latest version to AWS SaaS Boost. Whenever a new version is uploaded it will be automatically deployed to all the tenants in your system. AWS SaaS Boost now has you ready to operate as a SaaS business. This includes operational and management tooling that's built into the AWS SaaS Boost environment.
Now that you have a feel for the AWS SaaS Boost technology and experience, let's look at the details that are involved in setting up AWS SaaS Boost.
AWS SaaS Boost uses a handful of technologies to orchestrate the installation process. Install and configure each of these prerequisites for your operating system if they aren't already installed:
- Java 11 Amazon Corretto 11
- Apache Maven (see Installation Instructions)
- AWS Command Line Interface version 2
- Git
- Node 14.15 (LTS)
- Yarn
If you would like to install AWS SaaS Boost using Cloud9, you can follow these instructions Install using AWS Cloud9 and then continue with Step 3.
With the tooling in place, you can now download the code and installation scripts for AWS SaaS Boost. Open your terminal window and navigate to the directory where you want to store the AWS SaaS Boost assets. Issue the following command to clone the AWS SaaS Boost repository:
git clone https://github.com/awslabs/aws-saas-boost ./aws-saas-boost
Now that you have the code, AWS SaaS Boost needs to be installed in an AWS account that you own and manage. The installation process executes scripts that provision and configure all the resources that are needed to set up AWS SaaS Boost. The system where you run the installation should have at least 4 GB of memory.
Before running the installation, setup your AWS user and CLI:
- Setup an IAM user in your AWS account with full admin permissions.
- Set up your AWS CLI credentials with an AWS Access Key and default region.
To initiate this process, perform the following steps:
- From the terminal window, navigate to the directory where you've downloaded AWS SaaS Boost (aws-saas-boost).
- Invoke the install command.
- If you're running on Linux or OSX, run:
sh install.sh - If you're running on Windows, run:
.\install.ps1
- If you're running on Linux or OSX, run:
- Select the option for a new installation.
- Enter the full path to your AWS SaaS Boost directory: /<mydir>/aws-saas-boost.
- Enter the name of the SaaS Boost environment (dev, QA, test, sandbox, etc.).
- Enter the email address of the AWS SaaS Boost administrator who will receive the initial temporary password.
- Indicate whether you would like the metrics and analytics features of AWS SaaS Boost to be installed (Y/N). This is optional and will provision a Redshift cluster.
- If you enter Y, you are prompted for QuickSight setup. To select Y for Quicksight setup, you must have already registered for at least a Standard account of Quicksight in your AWS Account by following the steps at https://docs.aws.amazon.com/quicksight/latest/user/signing-up.html.
- If your application is Windows based and needs a shared file system, a Managed Active Directory must be deployed to support Amazon FSx for Windows File Server. Select y or n as needed.
- Review the settings for your installation. Enter y to proceed or n to re-enter or adjust the values.
The execution of this process will take 30-45 minutes to provision and configure all the resources (this will vary based on the options you've selected). Detailed logs from the installation process are stored in saas-boost-install.log.
After the installation completes, you will receive a message at the email address you provided during the installation process. This message includes a link with a URL to the AWS SaaS Boost administration application. The message appears as follows:
Copy the temporary password that is shown here. Select the link to the AWS SaaS Boost administration application. The following login appears:
Enter admin for the user name and enter the temporary password that was delivered in the email referenced earlier. Since you're logging in with a temporary password, you're prompted to enter a new password for your account. The screen appears as follows:
After you've logged in to the AWS SaaS Boost administration application, the first thing you need to do is configure the environment to align it with the needs of your application. To set up the application, select Application from the navigation on the left side of the screen. A page appears similar to the following:
While this Getting Started Guide doesn't document each of the fields on the application settings page, the options you configure are essential to getting your application working. Here you define the footprint of how your application is configured for your tenants as they onboard.
You also set up key attributes that correlate directly to details that are part of your application's Docker configuration (container port, mount point, database settings, file system settings, and so on). Review the options for these settings before deploying your application.
Next, upload your application. As mentioned earlier, AWS SaaS Boost requires an application to be containerized as a Docker image before it can be published to the AWS SaaS Boost application repository. From the Summary page, click the View details link next to the ECR Repository URL listing to see the proper Docker push commands to upload your image.
This section goes through the process of uploading a sample application to give you a feel for how this process works. We've provided a simple example application as part of the AWS SaaS Boost repo.
Just as you would configure AWS SaaS Boost to support the requirements of your application, we must configure the application settings properly for this sample app. This sample application relies on the following configuration in AWS SaaS Boost.
- Give the application a Name
- You can leave Compute Size set to Small
- Minimum and Maximum Instance Count can be 1 and 2 respectively
- Container OS is Linux
- Set the Container Port to 8080
- Set the Health Check URL to /index.html
- Enable the Provision a File System for the application checkbox
- Set the Mount point to /mnt
- Enable the Provision a database for the application checkbox
- Select any of the available databases (MariaDB with a db.t3.micro instance class will provision the fastest)
- Enter a Database Name, Username, and Password. You do not need to provide a SQL file for database initialization.
Once you have saved your Application Setup, you can build and containerize the sample application. To create a Docker image of this sample application, you will need to have Docker running on your local machine. Navigate to the samples/java/ directory in your clone of the AWS SaaS Boost repo and execute the build script which will build, containerize, and push your containerized application to the AWS SaaS Boost ECR repository. You can review the steps in this example shell script to see how you might enhance your current build process for your application to integrate with AWS SaaS Boost.
cd aws-saas-boost/samples/java
sh build.shThis script prompts you for your AWS SaaS Boost environment. Enter the environment label that you specified when you ran the AWS SaaS Boost installer. When this script finishes, you have published your application to the AWS SaaS Boost application repository. To verify this, open the AWS Console, navigate to the Amazon ECR repositories, and verify that your application was uploaded. As you make changes to the application, you can execute the build script again to update your application.
You can now onboard a new tenant to deploy your containerized application. Navigate to the Onboarding page of the administration application and click the Provision Tenant button. Once the onboarding process completes, you'll be able to access that tenant's instance of the sample application by navigating to the Tenants page of the administration application, then go to the tenant detail page, and finally clicking on the Load Balancer DNS link.
This guide provides a high-level view into the basic steps that are required to set up AWS SaaS Boost. As you think about moving a workload into AWS SaaS Boost, examine the broader capabilities of AWS SaaS Boost in more detail. This means looking more carefully at the configuration options for your application and how they map to the different AWS SaaS Boost application settings.
After familiarizing yourself with the overall experience, you will have a better sense about how your application fits in the AWS SaaS Boost model. A review of the AWS SaaS Boost User Guide and Developer Guide will also allow you to better understand how you might configure AWS SaaS Boost to align with the needs of your solution.
The steps needed to containerize vary depending on the nature of your application. Here are some resources that provide information on containerizing applications: