Skip to content

Update README with correct handler usage #55

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Sep 8, 2025
Merged

Update README with correct handler usage #55

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6334582
Update README with correct handler usage
Sep 5, 2025
b521b7c
Update README with deprecation message of 2.x versions
Sep 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 19 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,17 @@ You can include this package in your preferred base image to make that base imag

## Requirements
The Ruby Runtime Interface Client package currently supports ruby 3.0 and above.

## Migration from 2.x to 3.x

**Important**: Version 2.x is deprecated. Please upgrade to version 3.x. For more information about Lambda runtime support, see the [AWS Lambda runtimes documentation](https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html).

**Breaking Change**: Version 3.0.0 introduced a change in how the handler is specified:

- **Version 2.x**: Handler was passed as a command line argument
- **Version 3.x+**: Handler must be specified via the `_HANDLER` environment variable

If you're upgrading from 2.x, update your Dockerfile to use the `_HANDLER` environment variable instead of relying on `CMD` arguments.

## Usage

Expand Down Expand Up @@ -39,7 +50,9 @@ Or install it manually as:

The next step would be to copy your Lambda function code into the image's working directory.
You will need to set the `ENTRYPOINT` property of the Docker image to invoke the Runtime Interface Client and
then set the `CMD` argument to specify the desired handler.
set the `_HANDLER` environment variable to specify the desired handler.

**Important**: The Runtime Interface Client requires the handler to be specified via the `_HANDLER` environment variable.

Example Dockerfile:
```dockerfile
Expand All @@ -57,23 +70,16 @@ RUN gem install bundler
# Install the Runtime Interface Client
RUN gem install aws_lambda_ric

# If you want to install Runtime Interface Client From Source, you can uncomment the following `ADD` and `RUN` layers.
# Do not forget to comment/remove the above `RUN gem install aws_lambda_ric` command.
# ADD https://github.com/aws/aws-lambda-ruby-runtime-interface-client.git /aws_lambda_ric
# RUN cd /aws_lambda_ric && \
# make init && \
# make build && \
# gem install --local /aws_lambda_ric/pkg/aws_lambda_ric-3.0.0.gem && \
# rm -rf /aws_lambda_ric

# Copy function code
RUN mkdir -p ${FUNCTION_DIR}
COPY app.rb ${FUNCTION_DIR}

WORKDIR ${FUNCTION_DIR}

# Set the handler via environment variable
ENV _HANDLER="app.App::Handler.process"

ENTRYPOINT ["/usr/local/bin/aws_lambda_ric"]
CMD ["app.App::Handler.process"]
```

Note that the `ENTRYPOINT` may differ based on the base image used. You can find the correct path by running an
Expand Down Expand Up @@ -119,9 +125,10 @@ mkdir -p ~/.aws-lambda-rie && \

```shell script
docker run -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080 \
-e _HANDLER="app.App::Handler.process" \
--entrypoint /aws-lambda/aws-lambda-rie \
myfunction:latest \
/usr/local/bin/aws_lambda_ric app.App::Handler.process
/usr/local/bin/aws_lambda_ric
```

This runs the image as a container and starts up an endpoint locally at `http://localhost:9000/2015-03-31/functions/function/invocations`.
Expand Down