[Research]: Running AWS Infrastructure Locally

[AshtonStephens]

Completing the issue description and arriving at a conclusion is the deliverable of this issue.

Research - Running AWS Infrastructure Locally

This ticket holds the research relating to running AWS architecture locally and how it impacts sBTC-v1.

1. Summary

It's very feasible to run an API that uses DynamoDB, API Gateway, and AWS Lambda locally without any internet connection. Proof of concept PR: AshtonStephens/simple-aws-website#1

2. Context & Relevance

We need to be able to test all sBTC-v1 infrastructure locally, and while there are a lot of production benefits to using AWS, local environments are a weak point for AWS constructs . We want to determine if we can run AWS Lambda, API Gateway, and DynamoDB for the Deposit API infrastructure locally.

• This research is required to verify the approach for [Design]: Deposit API LLD #50
• Addresses concerns in [Design]: Deposit API #41
• May impact [Design]: Test Environments LLD #58

3. Research

3.1 Research Conclusions

We can run all the AWS related infrastructure for the DepositAPI locally and it works very well.

You need to download and run sam which is slightly annoying because doesn't fit neatly into docker compose, but on its own it works seamlessly. In the example I created there's a docker compose file that spins up a local version of DynamoDB as a service and then connects the SAM environment to it via a shared docker network.

I'm sure there are clever ways to make this fit neatly with a docker compose setup, but in my demo the docker compose spins up first, and then the sam command run. This is fine because the build script takes care of everything; we'll want to have clean build scripts for sBTC-v1 as well.

3.1.1 Research Approach

I used an existing AWS project that I know works on AWS, simulated it locally, and checked that its behavior on AWS matched that of my local machine. I've linked the proof of concept above, and here for reference.

3.2 External Resources

• Example setup of AWS Lambda with Kong: https://thinkingeek.com/2023/12/24/testing-api-gateway-docker-lambdas/
• Using A local DynamoDB instance: https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal
• Bespoke AWS tool for running local CDK constructs (not Docker): https://github.com/aws-samples/aws-sam-java-rest

---

Closing Checklist

• The takeaway from this issue is clearly documented in the description of this ticket.~
• Everyone necessary has reviewed the resolution and agrees with the takeaways. The proof of concept works.
• This ticket has or links all the information necessary to familiarize a contributor with the topic and how it was resolved.

[AshtonStephens]

So far the lambda is easy to run locally mostly following the setup from the thinkgeek example.

Docker compose at project root:

services:

  lambda:
    build:
      context: lambda
    container_name: lambda
    ports:
      - 9000:8080
    environment:
      MESSAGE_TABLE_NAME: MessageTable-XXXXXXXXXXXX-us-west-2-dev
      AWS_DEFAULT_REGION: us-west-2

    networks:
      - lambda-example
      
    # ... kong part is having issues ... 
      
networks:
  lambda-example:

Dockerfile at path ./lambda/Dockerfile

FROM public.ecr.aws/lambda/python:3.12

# Copy function code
COPY src/entrypoint.py ${LAMBDA_TASK_ROOT}

# Set the CMD to your handler (could also be done as a parameter override outside of the Dockerfile)
CMD [ "entrypoint.handler" ]

And then the following curl "works" when you run this in project root, but has errors because there's no DynamoDB container or other services.

    docker compose down lambda
    docker compose build
    docker compose up lambda -d
    curl --silent "http://localhost:9000/2015-03-31/functions/function/invocations" \
            -d '{"resource": "/messages", "httpMethod": "POST", "body": "demo message"}' \
            | jq

The example repository I'm using is AshtonStephens/simple-aws-website (also linked in the issue description) and requires APIGateway, Lambda, and DynamoDB.

[AshtonStephens]

SAM is actually a promising path because it can spin up a full API with an API Gateway specification based on an OpenAPI template. Additionally, the --docker-network for sam calls lets us connect an existing docker network to the api.

[AshtonStephens]

Got this all working locally:

• API Gateway
• AWS Lambda
• DynamoDB

I'm going to try SecretsManager now. Actually, I'm not because I don't think the DepositAPI needs secrets

[AshtonStephens]

I created a PR for the proof of concept in the demo repository I was using: AshtonStephens/simple-aws-website#1

[netrome]

Nice stuff!