Skip to main content

Configuring Infrastructure Providers

The providers are different implementations of the Booster runtime to allow Booster applications run on different cloud providers or services. They all implement the same interface, and the main idea behind the providers is that no matter what the developer chooses as backend, they won't need to know anything about the underlying infrastructure.

Currently, the Booster framework provides three provider packages:

  • framework-provider-azure-*
  • framework-provider-aws-* (deprecated - See PR #1477)
  • framework-provider-local-* (for local testing)

Booster uses sensible defaults, convention over configuration, and code inference to reduce dramatically the amount of configuration needed. However, there are some aspects that can't be inferred (like the application name) or the provider library used for each environment.

Booster configuration

You configure your application by calling the Booster.configure() method. There are no restrictions about where you should do this call, but the convention is to do it in your configuration files located in the src/config folder. This folder will get automatically generated for you after running the boost new:project <project-name> CLI command.

This is an example of a possible configuration:

import { Booster } from '@boostercloud/framework-core'
import { BoosterConfig } from '@boostercloud/framework-types'

Booster.configure('pre-production', (config: BoosterConfig): void => {
config.appName = 'my-app-name'
config.providerPackage = '@boostercloud/framework-provider-aws'
})

The following is the list of the fields you can configure:

  • appName: This is the name that identifies your application. It will be used for many things, such us prefixing the resources created by the provider. There are certain restrictions regarding the characters you can use: all of them must be lower-cased and can't contain spaces. Two apps with different names are completely independent.

  • providerPackage: This field contains the name of the provider package that Booster will use when deploying or running your application.

  • enableGraphQLIntrospection This field allows to enable/disable get information about the GraphQL schema of your application from client side. By default is enabled but it is recommended to disable for security reasons in production applications.

  • assets: This is an array of relative paths from the root of the project pointing to files and folders with static assets. They will be included among the deployed files to the cloud provider. For example, imagine you are using the dotenv module so that all the environment variables you have in your .env files are loaded into memory in runtime. In order for this to work, you need to include your .env files as assets of your project, so that they are included when deploying. Assuming you only have a .env file in the root of your project, you should add the following to your configuration:

    config.assets = ['.env']

Providers setup

AWS Provider setup

In order to dpeloy your app to AWS you only need to provide Booster with the credentials of an AWS account and the framework will take care of the rest.

caution

Booster is free to use, but remember that the resources deployed to your cloud provider might generate some expenses.

In AWS, all the resources generated by Booster are part of the AWS free tier. When you're not eligible for the free tier, resources are charged on-demand. Deploying a Booster project and sending a few commands and queries should cost just a few cents.

In any case, make sure to un-deploy your application with the command boost nuke -e production if you're not planning to keep using it.

Creating an AWS account

If you don't have an AWS account, you can create one by following the instructions in the AWS documentation.

Getting the AWS credentials

Once you have an AWS account, you need to get the credentials that Booster needs to deploy your application. You can follow the instructions in the AWS documentation to get them.

Booster needs you to get the following credentials:

  • Access Key ID
  • Secret Access Key

Make sure you get them, as they will be needed in the next step.

Setting the AWS credentials on Booster

Booster needs to know how to authenticate against your AWS account. For that reason, create a folder called .aws under your home folder, and a file inside called credentials with this syntax:

[default]
aws_access_key_id=<YOUR ACCESS KEY ID>
aws_secret_access_key=<YOUR SECRET ACCESS KEY>

AWS Provider configuration

To configure AWS as a provider you need to meet certain prerequisites:

  • Check @boostercloud/framework-provider-aws is listed in your app package.json dependencies.
  • Check @boostercloud/framework-provider-aws-infrastructure is listed in your app package.json devDependencies.
  • Check both dependencies are installed, otherwise use npm install in the root of your project.

Now go to your config.ts file, import the aws provider library and set up your app environment.

import { Booster } from '@boostercloud/framework-core'
import { BoosterConfig } from '@boostercloud/framework-types'
import { Provider as AWSProvider } from

Booster.configure('production', (config: BoosterConfig): void => {
config.appName = 'my-app-name'
config.providePackage = '@boostercloud/framework-provider-aws'
})

Open your terminal and run the deployment command

boost deploy -e production

Now just let the magic happen, Booster will create everything for you and give you back your app ready to use URL. 🚀

Azure Provider Setup

Booster applications can be deployed to Microsoft Azure. To do so, you need to have an Azure account and to have the Azure CLI installed on your computer.

caution

Booster is free to use, but remember that the resources deployed to your cloud provider might generate some expenses.

In Azure, when you're not eligible for the free tier, resources are charged on-demand. Deploying a Booster project and sending a few commands and queries should cost just a few cents.

In any case, make sure to un-deploy your application with the command boost nuke -e production if you're not planning to keep using it.

Creating an Azure account

As mentioned, you need to have an Azure account. If you don't have one, you can create one from the Microsoft SignUp page. You can also use your existing Microsoft account to create an Azure account.

Installing the Azure CLI

Once you have created the Azure account, you need to install the Azure CLI on your computer. You can do it by following the instructions on the official documentation. You may also need to install jq on your system.

Azure Provider configuration

To configure Azure as a provider you need to meet certain prerequisites:

  • Install jq in your system.
  • Install the terraform CLI.
  • Check @boostercloud/framework-provider-azure is listed in your app package.json dependencies.
  • Check @boostercloud/framework-provider-azure-infrastructure is listed in your app package.json devDependencies.
  • Check both dependencies are installed, otherwise use npm install in the root of your project.

At this moment you have to log in you Azure account using the Azure CLI with the following command.

az login

You will get something like this:

[
{
"cloudName": "AzureCloud",
"homeTenantId": "00000000-0000-0000-0000-000000000000",
"id": "00000000-0000-0000-0000-000000000000",
"isDefault": true,
"managedByTenants": [],
"name": "Azure subscription name",
"state": "Enabled",
"tenantId": "00000000-0000-0000-0000-000000000000",
"user": {
"name": "boosteduser@boosteddomain.com",
"type": "user"
}
}
]

Keep the id from the login output around.

Then create a service pricipal that is a contributor to a chosen subscription running the following command.

az ad sp create-for-rbac --name <service-principal-name> --role="Contributor" --scopes="/subscriptions/<the-id-from-the-login-output>"
note

Remember to change <service-principal-name> for a custom one.

After the service principal is created, create a bash script with the following content. It will set up the necessary environment variables required by the provider in order to work:

#!/usr/bin/env bash

SP_DISPLAY_NAME="<service-principal-name>" #replace <service-principal-name> with the name of your own SP
REGION="East US" #replace with a region of your choice, see full list here: https://azure.microsoft.com/en-us/global-infrastructure/locations/
AZURE_MAX_CONTAINER_THROUGHPUT=1000 #replace with a desired value for CosmosDB container throughput
AZURE_MAX_DATABASE_THROUGHPUT=1000 #replace with a desired value for CosmosDB database throughput

export AZURE_APP_ID=$(az ad sp list --display-name ${SP_DISPLAY_NAME} | jq -r '.[].appId')
export AZURE_TENANT_ID=$(az ad sp list --display-name ${SP_DISPLAY_NAME} | jq -r '.[].appOwnerOrganizationId')
export AZURE_SECRET=$(az ad sp credential reset --id ${AZURE_APP_ID} | jq -r '.password')
export AZURE_SUBSCRIPTION_ID=$(az account show | jq -r '.id')
export REGION=$REGION
export AZURE_MAX_CONTAINER_THROUGHPUT=$AZURE_MAX_CONTAINER_THROUGHPUT
export AZURE_MAX_DATABASE_THROUGHPUT=$AZURE_MAX_DATABASE_THROUGHPUT
note

Remember to have jq installed in your system.

Now go to your config.ts file, import the aws provider library and set up your app environment.

import { Booster } from '@boostercloud/framework-core'
import { BoosterConfig } from '@boostercloud/framework-types'

Booster.configure('production', (config: BoosterConfig): void => {
config.appName = 'my-app-name'
config.providerPackage = '@boostercloud/framework-provider-azure'
})

Open your terminal and run the bash file to export you env variables and the deploy command

source <path-to-your-bash-file> && boost deploy -e production
note

Remember to have the terraform CLI installed in your system.

Now just let the magic happen, Booster will create everything for you and give you back your app ready to use URL. 🚀

Azure synth command

Azure provider implements the experimental Booster synth command. This command will generate Terraform templates from your code. It will also generate needed files to deploy your Booster application using cdktf.

Running synth command, for example boost synth -e production will generate following files:

  • A file cdktf.json: A basic json file to deploy your application using cdktf
  • A folder cdktf.out: with the Terraform templates.

Booster deploy command for Azure will deploy your application using the generated templates. You don't need to run the synth command for deploy your application, the deploy command will generate the templates before deploy for you.

Once you have the new files and folders generates you could use cdktf to deploy your application if you want to.

Azure and CI/CD environments

It is possible to deploy your Azure infrastructure using the Terraform templates generated by the synth command using Terraform executable.

To deploy a Booster application using the Terraform templates generated by the Booster synth command:

  1. Navigate to
> cd cdktf.out/stacks/<application name><environment name>
  1. Run (only the first time)
> terraform init
  1. Run
> terraform plan --out plan
  1. Run
> terraform apply "plan"

You could follow similar steps to integrate the Azure Booster deploys in your CI/CD environment.

  1. Navigate to
> cd cdktf.out/stacks/<application name><environment name>
  1. Copy functionApp.zip to the destination folder
> cp functionApp.zip <destination>

After copying the files you should have the following structure:

<application>
├── cdktf.out
│ └── stacks
│ └── <application name><environment name>
│ └── cdk.tf.json

Now deploy the template:

  1. Run (only the first time)
> terraform init
  1. Run
> terraform plan --out plan
  1. Run
> terraform apply "plan"

Finally, you need to upload the source code. The main options are (more info):

  1. Using az-cli. Run
> az functionapp deployment source config-zip -g <resource_group> -n \
<app_name> --src ./functionApp.json
  1. Using REST APIs. Send a POST request to https://<app_name>.scm.azurewebsites.net/api/zipdeploy. Example:
>  curl -X POST -u <deployment_user> --data-binary @"<zip_file_path>" https://<app_name>.scm.azurewebsites.net/api/zipdeploy
note

Remember to follow the Azure Provider steps in this page to set up your credentials correctly

Azure host.json file

Azure Provider will generate a default host.json file if there is not a host.json entry in the config.assets array.

If you want to use your own host.json file just add it to config.assets array and Booster will use yours.

Local Provider

All Booster projects come with a local development environment configured by default, so you can test your app before deploying it to the cloud.

You can see the configured local environment in your src/config/config.ts file:

Booster.configure('local', (config: BoosterConfig): void => {
config.appName = 'my-store'
config.providerPackage = '@boostercloud/framework-provider-local'
})

In order to start your application using the local provider, use the following command:

boost start -e local

Where local is one of your defined environments with the Booster.configure call.

Cleaning Local Data for New Changes

When making changes to your entities and events, you might need to reset the local environment to accommodate these changes. The application creates a .booster folder to store relevant information. To clean the local data and reset the environment:

  1. Locate the .booster folder in your project directory.
  2. Delete the contents of the .booster folder or the folder itself.

This action will clear the local data and allow you to proceed with your new changes effectively.