fix(examples): move nginx-zip to provided.al2023, drop the PHP examples (#832)

fix(examples): use provided.al2023 runtime in nginx-zip

provided.al2 was deprecated on 2026-07-31 (creation disabled 2027-02-01, updates 2027-03-03), so sam validate --lint flags it as W2531 and the examples workflow fails.

Verified the example still works on AL2023 by mounting the Nginx123X86:12 layer contents at /opt in public.ecr.aws/lambda/provided:al2023: nginx 1.23.3 starts, GET / returns 200 and GET /images/space.jpeg returns the 1.3 MB binary response with no errors logged. The layer’s only bundled library is libcrypt.so.1, which resolves from /opt/lib on the default LD_LIBRARY_PATH.

chore(examples): drop the PHP examples

Both PHP examples were built on artifacts frozen in March 2023 that are tied to Amazon Linux 2, and neither can move to AL2023 without those artifacts being rebuilt:

php-zip used the Php82FpmNginx{X86,Arm}:13 layers. On provided.al2023 php-fpm still starts, but the extensions declared in php/php.d/extensions.ini fail to load because they link against AL2-only libraries: openssl, curl and ftp need libssl.so.10/libcrypto.so.10 (OpenSSL 1.0.2), awscrt needs libcrypto.so.10, gd needs libpng15.so.15, and imagick needs libfontconfig.so.1. AL2023 ships OpenSSL 3.x, so a user extending the example would silently lose HTTPS/TLS support.
php (Docker) is based on public.ecr.aws/awsguru/php:82.2023.3.11.1, the same AL2 build of PHP 8.2.

Rather than ship examples whose runtime is deprecated (provided.al2, creation disabled 2027-02-01) or whose extension set is quietly broken, drop them. Neither example was covered by the test-image or test-zip CI matrices, so no test coverage is lost. README.md still points PHP users at Bref, and the guide still lists Laravel on Lambda as a community example.

AWS Lambda Web Adapter

A tool to run web applications on AWS Lambda

AWS Lambda Web Adapter allows developers to build web apps (http api) with familiar frameworks (e.g. Express.js, Next.js, Flask, SpringBoot, ASP.NET and Laravel, anything speaks HTTP 1.1/1.0) and run it on AWS Lambda. The same docker image can run on AWS Lambda, Amazon EC2, AWS Fargate, and local computers.

Lambda Web Adapter

📖 Read the full User Guide

Features

Run web applications on AWS Lambda
Supports Amazon API Gateway Rest API and Http API endpoints, Lambda Function URLs, and Application Load Balancer
Supports Lambda managed runtimes, custom runtimes and docker OCI images
Supports Lambda Managed Instances for multi-concurrent request handling
Supports any web frameworks and languages, no new code dependency to include
Automatic encode binary response
Enables graceful shutdown
Supports response payload compression
Supports response streaming
Supports multi-tenancy via tenant ID propagation
Supports non-http event triggers

Quick Start

Docker Images

Add one line to your Dockerfile:

COPY --from=public.ecr.aws/awsguru/aws-lambda-adapter:1.0.1 /lambda-adapter /opt/extensions/lambda-adapter

Pre-compiled multi-arch images (x86_64 and arm64) are available at public.ecr.aws/awsguru/aws-lambda-adapter. Non-AWS base images may be used since the Runtime Interface Client ships with the Lambda Web Adapter.

👉 Docker Images guide

Zip Packages

Attach the Lambda Web Adapter layer to your function:
- x86_64: arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerX86:28
- arm64: arn:aws:lambda:${AWS::Region}:753240598075:layer:LambdaAdapterLayerArm64:28
Set environment variable AWS_LAMBDA_EXEC_WRAPPER to /opt/bootstrap
Set function handler to your startup script, e.g. run.sh

👉 Zip Packages guide (includes AWS China region ARNs and Windows caveats)

Configurations

The readiness check port/path and traffic port can be configured using environment variables. These environment variables can be defined either within docker file or as Lambda function configuration.

Environment Variable	Description	Default
AWS_LWA_PORT	traffic port (falls back to `PORT`)	“8080”
AWS_LWA_READINESS_CHECK_PORT	readiness check port	AWS_LWA_PORT
AWS_LWA_READINESS_CHECK_PATH	readiness check path	“/“
AWS_LWA_READINESS_CHECK_PROTOCOL	readiness check protocol: “http” or “tcp”	“http”
AWS_LWA_READINESS_CHECK_HEALTHY_STATUS	HTTP status codes considered healthy (e.g., “200-399”)	“100-499”
AWS_LWA_ASYNC_INIT	enable asynchronous initialization for long initialization functions	“false”
AWS_LWA_REMOVE_BASE_PATH	the base path to be removed from request path	None
AWS_LWA_ENABLE_COMPRESSION	enable gzip/br compression for response body (buffered mode only)	“false”
AWS_LWA_INVOKE_MODE	Lambda function invoke mode: “buffered” or “response_stream”	“buffered”
AWS_LWA_PASS_THROUGH_PATH	the path for receiving event payloads from non-http triggers	“/events”
AWS_LWA_AUTHORIZATION_SOURCE	a header name to be replaced to `Authorization`	None
AWS_LWA_ERROR_STATUS_CODES	HTTP status codes that will cause Lambda invocations to fail (e.g. “500,502-504”)	None
AWS_LWA_LAMBDA_RUNTIME_API_PROXY	overwrites `AWS_LAMBDA_RUNTIME_API` to allow proxying request	None

Deprecation Notice: The following non-namespaced environment variables are deprecated and will be removed in version 2.0: HOST, READINESS_CHECK_PORT, READINESS_CHECK_PATH, READINESS_CHECK_PROTOCOL, REMOVE_BASE_PATH, ASYNC_INIT. Please migrate to the AWS_LWA_ prefixed versions. Note: PORT is not deprecated and remains a supported fallback for AWS_LWA_PORT.

Additionally, AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS has been removed in 1.0. Use AWS_LWA_READINESS_CHECK_HEALTHY_STATUS instead.

👉 Detailed configuration docs

Examples

👉 Examples organized by language

Acknowledgement

This project was inspired by several community projects.

Migrating from 0.x to 1.0

Environment Variables

All environment variables now use the AWS_LWA_ prefix. The old non-prefixed names still work but are deprecated and will be removed in version 2.0.

Old (Deprecated)	New
`READINESS_CHECK_PORT`	`AWS_LWA_READINESS_CHECK_PORT`
`READINESS_CHECK_PATH`	`AWS_LWA_READINESS_CHECK_PATH`
`READINESS_CHECK_PROTOCOL`	`AWS_LWA_READINESS_CHECK_PROTOCOL`
`REMOVE_BASE_PATH`	`AWS_LWA_REMOVE_BASE_PATH`
`ASYNC_INIT`	`AWS_LWA_ASYNC_INIT`

Note: PORT is not deprecated and remains a supported fallback for AWS_LWA_PORT.

Readiness Check Health Status

AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS has been removed. Use AWS_LWA_READINESS_CHECK_HEALTHY_STATUS instead, which accepts comma-separated codes and ranges:

# Old
AWS_LWA_READINESS_CHECK_MIN_UNHEALTHY_STATUS=400

# New (equivalent)
AWS_LWA_READINESS_CHECK_HEALTHY_STATUS=100-399

Similar Projects

Several projects also provide similar capabilities as language specific packages/frameworks.

Security

See SECURITY for vulnerability reporting and CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.