MerLoc is a live AWS Lambda function development and debugging tool. MerLoc allows you to run AWS Lambda functions on your local while they are still part of a flow in the AWS cloud remote.
MerLoc is a live AWS Lambda function development and debugging tool. MerLoc allows you to run AWS Lambda functions on your local while they are still part of a flow in the AWS cloud remote.
It currently supports Java, Go, Python, Node.js & .NET runtimes & works with serverless framework & AWS SAM under the hood.
Let's say that you have the following sample serverless architecture for your order application in your AWS account.
And you are developing the order-notification-service
.
With the help of MerLoc, you don’t need to
MerLoc makes it possible to
Additionally, MerLoc propagates IAM credentials from the real AWS Lambda environment to your local so your local function runs with the same credentials. So this means that you can also test and verify IAM permission issues on your local.
In the example shown above, when you run order-notification-service
locally with MerLoc,
order-request-service
and order-processing-service
will run on real AWS Lambda environment,
and you will get real published message (by order-processing-service
) from real order-notification-topic
on your local order-notification-service
and run as a part of real flow in the cloud.
MerLoc is included with free package of Thundra APM and you can also follow this repository and host your own MerLoc broker.
cd merloc-broker/stack/deployment
PROFILE=dev ./deploy.sh
Make sure that Docker is up and running before running this command as Docker is used to compile and build broker Lambda functions.
If you want to configure the region to deploy the broker, you can specify it by environment variable. For example to deploy the broker into us-west-2 region:
AWS_REGION=us-west-2 PROFILE=dev ./deploy.sh
Either you can get it from the AWS CDK outputs, for ex:
or from the AWS CloudFormation output, for ex:
After broker setup is complete, you also need to install following runtime components (as shown in the Architecture section):
Warning MerLoc GateKeeper setup requires different configurations for Go runtime. You can check here and here for the details.
There are default configurations for the broker in the merloc-broker/stack/.env
file.
To change the broker configurations, you can update the values in the .env
file here
and re-deploy the stack by running deploy.sh
.
If you want to use custom domain name for your broker URL configuration (instead of the generated AWS API Gateway endpoint URL), you need to create an AWS Hosted Zone and configure the following properties in the merloc-broker/stack/.env
file according to the Hosted Zone:
MERLOC_DOMAIN_NAME
: Specifies the root domain name to be used by MerLoc. Domain name of the target AWS Hosted Zone is expected to be set here. This configuration is mandatory if you want to use custom domain name.MERLOC_BROKER_WS_API_SUBDOMAIN_NAME
: Specifies the sub-domain name to be used by MerLoc broker. This configuration is optional and default value is merloc
.After configuring those settings, your full custom domain name will be ${MERLOC_BROKER_WS_API_SUBDOMAIN_NAME}.${MERLOC_DOMAIN_NAME}
and you will be able to use wss://${MERLOC_BROKER_WS_API_SUBDOMAIN_NAME}.${MERLOC_DOMAIN_NAME}
custom domain name as your broker URL configuration instead of the generated AWS API Gateway endpoint URL.
So let's say that you have an AWS hosted zone with domain name lambda.dev
. Then you set MERLOC_DOMAIN_NAME
to lambda.dev
and set MERLOC_BROKER_WS_API_SUBDOMAIN_NAME
to merloc
. So your full custom domain name will be merloc.lambda.dev
and you can use wss://merloc.lambda.dev
as your broker URL configuration.
Everyone is very welcome to contribute to this repository. Feel free to raise issues or to submit Pull Requests.
To report a bug or request a feature, create a GitHub Issue. Please ensure someone else has not created an issue for the same topic.
Licensed under Apache License 2.0.