Using Quarkus Amazon Lambda without Docker Engine

A comprehensive guide to configure and run Quarkus with LocalStack without Docker dependency

Highlights

Configuration: Detailed instructions on setting up application.properties for AWS Lambda with LocalStack.
LocalStack Management: Methods to install and manage LocalStack manually using Python.
Development Workflow: Leveraging Quarkus Dev Services and testing paradigms without relying on Docker.

Introduction

Quarkus is a modern, lightweight Java framework built for Kubernetes and cloud-native environments, which now includes robust support for AWS Lambda functions. Typically, Quarkus leverages Docker and its development ecosystem to simplify the management of dependencies like LocalStack—a fully functional local AWS cloud stack. However, it is possible to configure and use the quarkus-amazon-lambda extension without a dedicated Docker engine. This guide details how to set up your Quarkus application to work with LocalStack manually, enabling you to run and test AWS Lambda functions locally without the dependency on Docker containers.

Setting Up Your Quarkus Project

Project Initialization

Begin by creating a new Quarkus project that includes the amazon-lambda and other necessary extensions. Use the Maven plugin for Quarkus to quickly scaffold a project:

Maven Command


# Create a new Quarkus project with Lambda support
mvn io.quarkus.platform:quarkus-maven-plugin:3.17.0:create \
  -DprojectGroupId=org.acme \
  -DprojectArtifactId=amazon-lambda-quickstart \
  -DclassName="org.acme.lambda.QuarkusLambdaSyncResource" \
  -Dpath="/sync" \
  -Dextensions="resteasy-reactive-jackson,amazon-lambda"
cd amazon-lambda-quickstart

This command sets up a project structure with necessary dependencies such as RESTEasy Reactive and Jackson for JSON processing along with the quarkus-amazon-lambda extension.

Manual Setup of LocalStack

LocalStack Installation Using Python

Since Docker is not available or desired in your environment, the first step is to install LocalStack using Python. Ensure you have Python 3.7 or higher before installing LocalStack.

Installation Steps


# Install LocalStack using pip
pip install localstack

# Start LocalStack on your local machine
localstack start

LocalStack simulates AWS services locally, making it convenient for testing AWS Lambda, S3, SQS, DynamoDB, and many more. Running LocalStack manually removes the reliance on Docker, although it might require additional system resources depending on your environment.

Configuration for Manual Management

With LocalStack installed, configure it to run using the default endpoint (typically http://localhost:4566). To ensure that your Quarkus application connects appropriately, update your application.properties file with the following configuration settings:

application.properties


# Override the Lambda endpoint to use LocalStack
quarkus.lambda.endpoint-override=http://localhost:4566

# Set the AWS region for your Lambda functions
quarkus.lambda.aws.region=us-east-1

# Configure static AWS credentials (suitable for local testing)
quarkus.lambda.aws.credentials.type=static
quarkus.lambda.aws.credentials.static-provider.access-key-id=test-key
quarkus.lambda.aws.credentials.static-provider.secret-access-key=test-secret

# Optionally, disable automatic dev services to prevent Quarkus from trying to start a container if one is already running
%test.quarkus.devservices.enabled=false
quarkus.devservices.enabled=false
quarkus.datasource.devservices.enabled=false

These properties ensure that AWS Lambda endpoints and other related services connect to the LocalStack instance running on http://localhost:4566. The static providers allow dummy credentials for local testing. Disabling some dev services prevents Quarkus from attempting to start LocalStack in a containerized way, making it rely solely on your manually started instance.

Leveraging Quarkus Dev Services Without Docker

Using Dev Services for Faster Development

While the default behavior of Quarkus is to integrate with Docker for certain development conveniences, you can circumvent this by relying on manual service management. Quarkus Dev Services is capable of detecting an already running LocalStack container or manually managed instance. When configured correctly, it leverages the service endpoint you have specified in your configuration files.

Run your Quarkus application in development mode using the following command:

Running in Dev Mode


./mvnw quarkus:dev

In this mode, the application watches for code changes and automatically refreshes the environment. The configured static properties allow your Lambda functions and other AWS services to connect seamlessly with your LocalStack instance without invoking Docker containers.

Testing Lambda Functions Locally

For thorough testing during development, you can simulate Lambda invocations directly within the Quarkus ecosystem. Quarkus provides a mock AWS Lambda event server that replicates the behavior of AWS Lambda in a local environment. This way, you can test event-triggered functions without deploying them to the actual AWS environment.

To invoke your functions, send HTTP requests to your application (typically running on http://localhost:8080 in Dev Mode). For example, you could use tools like curl or Postman to test your functions:

Example Using curl


curl -d '{"key": "value"}' -H "Content-Type: application/json" -X POST http://localhost:8080

This approach enables you to simulate Lambda events and view how your functions process the provided input, all without relying on the Docker engine.

Additional Configuration and Considerations

Ensuring Consistent AWS Profiles

For local testing environments, it is often necessary to configure your AWS CLI to use the same credentials that are defined for your Quarkus application. Create or update an AWS profile dedicated to LocalStack. Execute:

Setting Up an AWS Profile


aws configure --profile localstack
AWS Access Key ID [None]: test-key
AWS Secret Access Key [None]: test-secret
Default region name [None]: us-east-1
Default output format [None]:

This ensures that any AWS command-line tools or SDK operations during development mirror the configuration activated within Quarkus, thereby avoiding any discrepancies between environments.

Managing Service Endpoints in a Table

The following table lists the common service endpoints configuration for LocalStack in the application.properties file. This aids quick reference and configuration uniformity:

Service	Endpoint	Configuration Property
Lambda	http://localhost:4566	quarkus.lambda.endpoint-override
DynamoDB	http://localhost:4566	aws.dynamodb.endpoint
S3	http://localhost:4566	aws.s3.endpoint
SQS	http://localhost:4566	aws.sqs.endpoint

This table ensures that each part of your application communicates with the locally managed AWS services running under LocalStack's umbrella.

Alternative Deployment Approach

Although completely removing Docker from your development flow is achievable, note that production deployment to AWS Lambda might require packaging your application either as a native image or as a ZIP archive with dependencies. Many organizations compartmentalize their local development process from their deployment pipeline, so a Docker-free environment is often reserved solely for local development and testing.

When preparing your application for deployment on AWS Lambda, ensure you follow the correct packaging steps. In many cases, a native image build (or a traditional build) will be used alongside containerization for deployment, which may involve Docker during the packaging stage, but not necessarily during local development.

Practical Example of a Full Setup

Step-by-Step Configuration Recap

Here is a summarized walkthrough of the process to set up your Quarkus Amazon Lambda project without leveraging a Docker engine:

Create your Quarkus project with the AWS Lambda extension, using Maven to initialize the project structure.
Install and launch LocalStack manually using Python's pip to simulate the AWS environment on your local machine.
Configure the application.properties file to point your Lambda endpoint and other AWS service endpoints to the LocalStack instance running at http://localhost:4566. Make use of static credentials for local testing purposes.
Disable unnecessary dev services if they attempt to automatically spin up new containers, ensuring that connectivity remains always with your manually managed server.
Run the application in development mode using ./mvnw quarkus:dev and test AWS Lambda functions by sending HTTP requests simulating the event payloads.
Ensure you configure AWS CLI and use the same credentials in a dedicated profile for consistency when running any AWS commands for local integration.

By following this outlined process, you can enjoy the benefits of Quarkus’s speedy development cycle without the overhead or dependency of a Docker engine. This method is particularly valuable in environments where Docker is either impractical or unsupported.

Conclusion

In summary, using the quarkus-amazon-lambda extension without relying on Docker involves careful configuration of your local AWS endpoints, manual management of LocalStack through Python, and precise adjustments within Quarkus’s development settings. This guide walked through the process of initializing a Quarkus project, installing and configuring LocalStack, and setting up the necessary properties in your application.properties file. Additionally, we highlighted how to adjust dev services settings and test your Lambda functions locally. Although completely eliminating Docker may have some trade-offs in terms of ease of setup, this approach significantly simplifies local development when managing system constraints or when Docker is not a viable option.

This comprehensive guide ensures that developers can maintain a rapid development cycle without the administrative overhead of container management, while still delivering the powerful, cloud-native functionalities that Quarkus and AWS Lambda provide.