Skip to content

deploy.md

Latest commit

 

History

History
264 lines (178 loc) · 10.5 KB

deploy.md

File metadata and controls

264 lines (178 loc) · 10.5 KB

TrackBuddy Deployment Guide

This guide walks you through deploying TrackBuddy, a Slack-integrated work logging and summary system using AWS Bedrock Agents.

Prerequisites

This deployment requires AWS CDK and TypeScript to be installed in your local integrated development environment (IDE) and for an AWS account to be bootstrapped. If this has not been done, refer to Getting started with the AWS CDK.

Required Tools

  • AWS Account with appropriate permissions
  • AWS CLI configured with credentials
  • CDK v2 installed (npm install -g aws-cdk)
  • Node.js 18+ and npm installed
  • Python 3.8+ and pip installed
  • Git for cloning the repository

Step 1: Create a new Slack application

After you have logged in to your Slack workspace, complete the following steps:

  1. Navigate to your Slack apps and create a new application.

  2. Choose From scratch when prompted.

  3. Provide an application name. For this deployment, use the name TrackBuddy.

  4. Choose your workspace and choose Create App.

  5. To provide permissions for your Slack application, choose OAuth & Permissions in your Slack application navigation pane.

  6. In the Scopes section, under Bot Token Scopes, add the following permissions:

    • commands
    • chat:write

  7. Under OAuth Tokens for Your Workspace, choose Install to [workspace name].

  8. Choose a channel that the Slack application will be accessed from. You may want to first create a dedicated channel in Slack for this purpose.

  9. Choose Allow.

  10. When the Slack application install is complete, copy the token value generated for Bot User OAuth Token to use in a later step.

  11. Under Settings in the navigation pane, choose Basic Information.

  12. In the App Credentials section, copy the value for Signing Secret and save this to use later.

Step 2: Enable model access in Amazon Bedrock

Complete the following steps to enable model access in Amazon Bedrock:

  1. On the Amazon Bedrock console, choose Model access in the navigation pane.

  2. Choose Modify model Access or Enable specific models (if this is the first time using Amazon Bedrock in your account).

  3. Select the models you want to use. For TrackBuddy, we use Anthropic's Claude 3.5 Haiku for the agent model in the US-EAST-1 AWS Region.

  4. Choose Next.

  5. Review the model selection and choose Submit.

    If you're not using the US-EAST-1 Region, the models available to request may differ.

  6. When the access request is complete, you will see the model's status shown as Access granted for the selected models.

Step 3: Deploy the TrackBuddy integration

In this section, you deploy TrackBuddy to your AWS account, which will deploy an API on API Gateway, Lambda functions, a DynamoDB table, and an Amazon Bedrock Agent with Action Groups.

  1. Clone the code from the GitHub repository:

    git clone https://github.com/gburger5/track-buddy.git
cd TrackBuddy

  2. Open the TrackBuddy directory in your preferred IDE and open the lib/trackbuddy-stack.ts file.

  3. Update the region variable if needed (we're using US-EAST-1 for this deployment):

    // Verify the region is set to us-east-1
const BEDROCK_MODEL_ID = "anthropic.claude-3-5-haiku-20241022-v1:0";

  4. Save the changes after all updates are complete.

  5. From the root of your repository, run the command:

    npm install

  6. Bootstrap CDK if this is your first time using CDK in the us-east-1 region:

    cdk bootstrap --region us-east-1

  7. Run the command cdk synth to perform basic validation of AWS CDK code. This generates a CloudFormation template from the AWS CDK stack, which can be reviewed in the cdk.out directory created in the root of the repository.

  8. Install Python dependencies for Lambda functions:

    # Install dependencies for SlackHandlerFunction
cd lambda/SlackHandlerFunction
pip install -r requirements.txt -t .
cd ../..

# Install dependencies for ActionFunction
cd lambda/ActionFunction
pip install -r requirements.txt -t .
cd ../..

  9. To deploy the application stack, run the following command, replacing the values with the token and the signing secret you created earlier:

    cdk deploy --context slackBotToken=xoxb-your-bot-token-here --context slackSigningSecret=your-signing-secret-here

    The AWS CDK will deploy the stack as a CloudFormation template. You can monitor the progress of the deployment on the AWS CloudFormation console.

    Additionally, AWS CDK will attempt to deploy the application stack to the default account and Region using the default credentials file profile. To change profiles, add the profile flag. For example:

    cdk deploy --profile [my-profile] --context slackBotToken=xoxb-your-bot-token-here --context slackSigningSecret=your-signing-secret-here

  10. When the deployment is complete, you will see an output similar to the following, which details the API endpoint that has just been deployed:

    TrackBuddyStack.ApiUrl = https://abc123def.execute-api.us-east-1.amazonaws.com/prod
TrackBuddyStack.AgentId = ABCD1234EF
TrackBuddyStack.AgentAliasId = EFGH5678IJ

    Copy the API endpoint URL for later use.

    You can also retrieve this URL on the Outputs tab of the CloudFormation stack TrackBuddyStack that was run to deploy this solution.

Step 4: Configure Slack Commands

  1. Switch back to the Slack API page.

  2. Under the Slack application you created, choose Slash Commands in the navigation pane and then choose Create New Command.

  3. Create the following four commands (make sure to include the Region and API ID that has been deployed):

    Command 1: /log

    • For Command, enter /log
    • For Request URL, enter https://[AWS-URL]/slack. For example, https://abc123def.execute-api.us-east-1.amazonaws.com/prod/slack
    • For Short Description, enter Log daily work activities
    • For Usage Hint, enter [work description]
    • Choose Save

    Command 2: /1:1

    • For Command, enter /1:1
    • For Request URL, enter https://[AWS-URL]/slack
    • For Short Description, enter Generate 1:1 meeting summary
    • For Usage Hint, enter (generates summary of past 7 days)
    • Choose Save

    Command 3: /midpoint

    • For Command, enter /midpoint
    • For Request URL, enter https://[AWS-URL]/slack
    • For Short Description, enter Generate mid-year summary
    • For Usage Hint, enter (generates summary of past 6 months)
    • Choose Save

    Command 4: /quarterly

    • For Command, enter /quarterly
    • For Request URL, enter https://[AWS-URL]/slack
    • For Short Description, enter Generate quarterly summary
    • For Usage Hint, enter [Q1/Q2/Q3/Q4] (auto-detects if not specified)
    • Choose Save

  4. Reinstall the Slack application to your workspace in the Install App section by choosing Reinstall next to the workspace name.

  5. Choose the channel where the Slack app will be deployed and choose Allow.

  6. In the Slack channel, you will see a message indicating that an integration with the channel has been added.

Step 5: Test the TrackBuddy integration

Complete the following steps to test the integration:

  1. Open the Slack channel selected in the previous steps and enter /log.

  2. The Slack application will be displayed. Choose the Slack application and enter your work description. For this test, we use the prompt "Working on TrackBuddy deployment documentation."

  3. The Slack application will respond with a confirmation that your work has been logged.

  4. Test the summary generation by entering /1:1.

  5. The application will process your request and provide a professional summary of your recent work activities.

  6. Test the other summary commands:

    • /midpoint for mid-year summaries
    • /quarterly for quarterly summaries

Step 6: Verify AWS Resources

Check DynamoDB

  1. Go to AWS Console → DynamoDB
  2. Find table: work-logs
  3. Verify work logs are being stored

Check Lambda Functions

  1. Go to AWS Console → Lambda
  2. Find functions:
    • TrackBuddyStack-SlackHandlerFunction-*
    • TrackBuddyStack-ActionFunction-*
  3. Check CloudWatch logs for any errors

Check Bedrock Agent

  1. Go to AWS Console → Bedrock → Agents
  2. Find agent: TrackBuddyAgent
  3. Verify it's in "Prepared" status

Troubleshooting

Common Issues

"Invalid signature" errors

  • Verify your Slack signing secret is correct
  • Check that the signing secret matches exactly (no extra spaces)

"Agent not found" errors

  • Ensure the Bedrock Agent is in "Prepared" status
  • Check that the agent alias is properly configured

Commands not responding

  • Verify API Gateway URL is correct in Slack app settings
  • Check Lambda function logs in CloudWatch

Permission errors

  • Ensure your AWS credentials have all required permissions
  • Check IAM roles created by CDK have proper policies

Debugging Steps

Check CloudWatch Logs

# View Slack Handler logs
aws logs tail /aws/lambda/TrackBuddyStack-SlackHandlerFunction-* --follow

# View Action Function logs  
aws logs tail /aws/lambda/TrackBuddyStack-ActionFunction-* --follow

Clean up

Complete the following steps to clean up your resources:

  1. From your terminal, run the following command, replacing the values with the token and the signing secret created earlier:

    cdk destroy --context slackBotToken=xoxb-your-bot-token-here --context slackSigningSecret=your-signing-secret-here

  2. When prompted, enter y to confirm the deletion of the deployed stack.

Note: This will delete all work logs stored in DynamoDB.

Conclusion

In this post, we implemented TrackBuddy, a solution that integrates Amazon Bedrock Agents with a Slack chat channel to allow users to log daily work activities and generate professional summaries for manager meetings. You can enhance this solution by customizing the summary formats or adding additional time periods for different reporting needs.

To get started, clone the GitHub repo and begin tracking your team's work activities with TrackBuddy. For more information about Amazon Bedrock, see Getting started with Amazon Bedrock.

Congratulations! 🎉 TrackBuddy is now deployed and ready to help your team track work and generate professional summaries for manager meetings.