LocalStack Dagger Module

A Dagger module for running LocalStack as a service within your Dagger pipelines.

This module simplifies integrating LocalStack into your development and testing workflows by:

• Starting LocalStack as a Dagger service.
• Securely handling LocalStack Auth Tokens using Dagger secrets.
• Automatically exposing standard LocalStack ports (4566 and 443).
• Allowing customization of the LocalStack container via environment variables.
• Optionally mounting the Docker socket for tests interacting with external containers.
• Managing LocalStack state using Cloud Pods (save/load/reset).
• Managing LocalStack Ephemeral Instances (create/list/delete/logs).

Prerequisites

• Dagger CLI installed
• Docker or a compatible container runtime
• LocalStack Auth Token (required)

Installation

You can install this module locally to use it in your own Dagger projects or pipelines:

dagger install github.com/localstack/localstack-dagger-module

You can then call its functions from the Dagger CLI or your Dagger SDK code.

Usage

Start LocalStack

# 1. Set your LocalStack auth token as an environment variable
export LOCALSTACK_AUTH_TOKEN="your-token"

# 2. Start LocalStack using the token from the environment
dagger -m github.com/localstack/localstack-dagger-module \
    call start --auth-token=env:LOCALSTACK_AUTH_TOKEN \
    up

LocalStack will run and be accessible at localhost:4566 and with any integration that LocalStack supports.

Customizing LocalStack

You can pass configuration variables in the following manner:

dagger -m github.com/localstack/localstack-dagger-module call start \
    --auth-token=env:LOCALSTACK_AUTH_TOKEN \
    --configuration='SERVICES=s3' \
    up

Mounting Docker Socket

To run emulated AWS services that rely on a container, like Lambda or ECS, you would need to mount Docker Socket into the LocalStack container.

dagger -m github.com/localstack/localstack-dagger-module call start \
    --auth-token=env:LOCALSTACK_AUTH_TOKEN \
    --docker-sock /var/run/docker.sock \
    up

Managing State with Cloud Pods

Cloud pods are persistent state snapshots of your LocalStack instance that can easily be stored, versioned, shared, and restored.

# Set your auth token
export LOCALSTACK_AUTH_TOKEN="your-token"

# Save the current state of your running LocalStack instance to a Cloud Pod
# Assumes you have a running instance started via 'dagger call start ... up' 
# And some cloud resources created via an integration
dagger -m github.com/localstack/localstack-dagger-module call state \
    --auth-token=env:LOCALSTACK_AUTH_TOKEN \
    --save=dagger-test-pod

# Reset the state of the running LocalStack instance
dagger -m github.com/localstack/localstack-dagger-module call state \
    --reset

# Load state from a Cloud Pod into your running LocalStack instance
dagger -m github.com/localstack/localstack-dagger-module call state \
    --auth-token=env:LOCALSTACK_AUTH_TOKEN \
    --load=dagger-test-pod

Managing Ephemeral Instances

Ephemeral Instances allows you to run a LocalStack instance in the cloud.

# Set your auth token
export LOCALSTACK_AUTH_TOKEN="your-token"

# Create a new Ephemeral Instance in LocalStack Cloud
dagger -m github.com/localstack/localstack-dagger-module call ephemeral \
    --auth-token=env:LOCALSTACK_AUTH_TOKEN \
    --operation=create \
    --name=my-temp-instance \
    --lifetime=120

# List active Ephemeral Instances
dagger -m github.com/localstack/localstack-dagger-module call ephemeral \
    --auth-token=env:LOCALSTACK_AUTH_TOKEN \
    --operation=list

# Get logs for an Ephemeral Instance
dagger -m github.com/localstack/localstack-dagger-module call ephemeral \
    --auth-token=env:LOCALSTACK_AUTH_TOKEN \
    --operation=logs \
    --name=my-temp-instance

# Delete an Ephemeral Instance
dagger -m github.com/localstack/localstack-dagger-module call ephemeral \
    --auth-token=env:LOCALSTACK_AUTH_TOKEN \
    --operation=delete \
    --name=my-temp-instance

Inputs

start

Used to configure and start the main LocalStack service.

Input	Description	Default	Example
auth-token	LocalStack Auth Token (as Dagger Secret). Required.	Required	dagger call start --auth-token=env:LOCALSTACK_AUTH_TOKEN
configuration	Comma-separated KEY=VALUE pairs for LocalStack environment variables.	None	dagger call start --configuration='DEBUG=1,PERSISTENCE=1'
docker-sock	Path to the Unix socket for the Docker daemon to mount into the container.	None	dagger call start --docker-sock=/var/run/docker.sock
image-name	Custom LocalStack Docker image name and tag.	localstack/localstack:latest	dagger call start --image-name=localstack/snowflake:latest

state

Used to manage the state of a running LocalStack instance using Cloud Pods.

Input	Description	Default	Example
auth-token	LocalStack Auth Token (as Dagger Secret). Required for save and load.	None	dagger call state --auth-token=env:LOCALSTACK_AUTH_TOKEN
load	Name of the LocalStack Cloud Pod to load into the running instance.	None	dagger call state --load=my-pod
save	Name under which to save the current state as a LocalStack Cloud Pod.	None	dagger call state --save=my-pod
reset	If true, resets the state of the running LocalStack instance.	False	dagger call state --reset
endpoint	LocalStack endpoint to connect to.	host.docker.internal:4566	dagger call state --endpoint=localhost:4566

ephemeral

Used to manage LocalStack Ephemeral Instances in LocalStack Cloud.

Input	Description	Default	Example
auth-token	LocalStack Auth Token (as Dagger Secret). Required for all operations.	Required	dagger call ephemeral --auth-token=env:LOCALSTACK_AUTH_TOKEN
operation	Action to perform: create, list, delete, logs.	Required	dagger call ephemeral --operation=create
name	Name of the ephemeral instance. Required for create, delete, logs.	None	dagger call ephemeral --name=my-instance
lifetime	Lifetime of the instance in minutes (only for create operation).	60	dagger call ephemeral --lifetime=120
auto-load-pod	Name of a Cloud Pod to automatically load when the ephemeral instance starts (only for create operation).	None	dagger call ephemeral --auto-load-pod=my-pod
extension-auto-install	Name of an extension to automatically install when the ephemeral instance starts (only for create operation).	None	dagger call ephemeral --extension-auto-install=my-extension --operation=create

Development

To contribute or make local changes to this module:

1. Clone the repository:

git clone https://github.com/localstack/localstack-dagger-module.git
cd localstack-dagger-module

2. Run dagger develop to set up the development environment.
3. Make your changes, typically within the Dagger module source files (e.g., in src/localstack/main.py).
4. Test your changes locally using dagger call as described in the sections above.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.