Skip to content

Installation

Initiate the BACE package and template

To initialize, navigate to the folder that you plan to store information on your computer. Clone the BACE repo:

git clone https://github.com/tt-econ/bace.git

By default, a bace folder will be created with the content of the repo. You can specify a different folder name in your git clone command. This is your project folder.

Build and Deploy Application

Make sure that Docker is running on your computer.

To create a Docker container that houses your application, from the root of your project directory, run

sam build

If you encounter any issue, the command sam build --debug can be helpful.

If you use AWS SSO, which is the recommended authentication process from the setup step, make sure you have signed in with aws sso login and have an active session.

Next, to deploy your application to AWS, run:

sam deploy --guided

The following provides example output. At each step, you hit ENTER to accept the default in brackets or provide a value to overwrite the default.

Please note that, when prompted, you should indicate that it is okay ('y') that the BaceFunction may not have authorization defined.

sam deploy --guided

Configuring SAM deploy
======================

        Looking for config file [samconfig.toml] :  Not found

        Setting default arguments for 'sam deploy'
        =========================================
        Stack Name [sam-app]: bace-app
        AWS Region [us-east-2]: ENTER
        #Shows you resources changes to be deployed and require a 'Y' to initiate deploy
        Confirm changes before deploy [Y/n]: ENTER
        #SAM needs permission to be able to create roles to connect to the resources in your template
        Allow SAM CLI IAM role creation [Y/n]: ENTER
        #Preserves the state of previously provisioned resources when an operation fails
        Disable rollback [y/N]: ENTER
        BaceFunction may not have authorization defined, Is this okay? [y/N]: y
        BaceFunction may not have authorization defined, Is this okay? [y/N]: y
        BaceFunction may not have authorization defined, Is this okay? [y/N]: y
        BaceFunction may not have authorization defined, Is this okay? [y/N]: y
        BaceFunction may not have authorization defined, Is this okay? [y/N]: y
        BaceFunction may not have authorization defined, Is this okay? [y/N]: y
        BaceFunction may not have authorization defined, Is this okay? [y/N]: y
        Save arguments to configuration file [Y/n]: ENTER
        SAM configuration file [samconfig.toml]: ENTER
        SAM configuration environment [default]: ENTER

If you run this command for the first time, you will also be asked to create a ECR repository, choose the default option Y.

Looking for resources needed for deployment:

Managed S3 bucket: aws-sam-cli-managed-default-samclisourcebucket-g3vpsjzvbenu
A different default S3 bucket can be set in samconfig.toml and auto resolution of buckets turned off by setting resolve_s3=False
        Image repositories: Not found.
        #Managed repositories will be deleted when their functions are removed from the template and deployed
        Create managed ECR repositories for all functions? [Y/n]:

This process may take a few moments. You will see the API Gateway endpoint URL that you can use to access your application once the process completes. An example output:

CloudFormation outputs from deployed stack
--------------------------------------------------------------------------------------------------------
Outputs
--------------------------------------------------------------------------------------------------------
Key                 BaceFunctionRole
Description         Implicit IAM Role created for BACE function
Value               arn:aws:iam::OMITTED:role/bace-app-BaceFunctionRole-OMITTED

Key                 BaceApi
Description         API Gateway endpoint URL for your BACE function.
Value               https://r3ue9e2bf3.execute-api.us-east-2.amazonaws.com/Prod/ # (1)

Key                 BaceFunction
Description         BACE Lambda Function ARN
Value               arn:aws:lambda:us-east-2:OMITTED:function:bace-app-BaceFunction-OMITTED
--------------------------------------------------------------------------------------------------------
  1. This is <your-URL>.

Congratulations! Your BACE template application is now up and running! Using the URL in the output of your sam deploy command, under BaceApi, you should see the following message in your browser:

{
    "message": "Hello! Your BACE application is up and running.",
    "author": "Pen Example Application"
}

You can also view an implementation of your AWS BACE app at <your-URL>/survey. In the example output above, this implementation will be accessed at https://r3ue9e2bf3.execute-api.us-east-2.amazonaws.com/Prod/survey. Try it.

Note: After deploying an application, the very first query may take around 10 to 20 seconds for the machine to get started. This is a one-time delay.

All of BACE's available API calls will now be available to you.

Note

If there are errors related to security tokens, your AWS credentials have not yet been established correctly on your machine.

Note

If you need to redo everything, first remove the entire app following the instructions in Delete your application.

Update Application

Whenever you update your application, you will need to repeat the above two steps:

sam build

to recompile the updated application, and

sam deploy

to deploy it to AWS. With /samconfig.toml saved, you will not have to reenter all the inputs and therefore the above command can replace sam deploy --guided.

Further material

The package also provides helpful tools:

  1. Prior to launching an experiment:
    • As you make changes to your application, to query and test your application, the provided API notebooks can be very helpful.
    • To perform simulated experiments, please refer to Simulation tools.
    • To perform load testing before launching a large experiment, please refer to Load testing.
  2. After launching an experiment: