Skip to content

Commit 8a6d3af

Browse files
HarshCasperHarshCasper
committed
add an updated README file
1 parent f2457f9 commit 8a6d3af

File tree

1 file changed

+160
-68
lines changed

1 file changed

+160
-68
lines changed

‎README.md‎

Lines changed: 160 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,194 @@
11
# LocalStack Dagger Module
22

3-
A Dagger module for running LocalStack (Community and Pro editions) as a service.
4-
5-
## Features
6-
7-
- Supports both LocalStack Community and Pro editions
8-
- Secure handling of authentication tokens using Dagger secrets
9-
- Automatic port mapping for:
10-
- Community Edition:
11-
- 127.0.0.1:4566:4566 (Main LocalStack endpoint)
12-
- Pro Edition:
13-
- All Community Edition ports
14-
- 127.0.0.1:443:443 (HTTPS endpoint)
15-
- Configurable environment variables for LocalStack customization
16-
- Docker socket mounting for container interactions
17-
- Management of ephemeral LocalStack instances in the cloud
3+
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
4+
[![LocalStack Dagger Module Tests](https://github.com/localstack/localstack-dagger-module/actions/workflows/test.yml/badge.svg)](https://github.com/localstack/localstack-dagger-module/actions/workflows/test.yml)
5+
6+
A [Dagger](https://dagger.io/) module for running [LocalStack](https://github.com/localstack/localstack) (Community and Pro image) as a service within your Dagger pipelines.
7+
8+
This module simplifies integrating LocalStack into your development and testing workflows by:
9+
10+
- Starting LocalStack Community or Pro editions as a Dagger service.
11+
- Securely handling LocalStack Auth Tokens using Dagger secrets.
12+
- Automatically exposing standard LocalStack ports (`4566` for Community/Pro, `443` for Pro).
13+
- Allowing customization of the LocalStack container via environment variables.
14+
- Optionally mounting the Docker socket for tests interacting with external containers.
15+
- Managing LocalStack state using [Cloud Pods](https://docs.localstack.cloud/user-guide/state-management/cloud-pods/) (`save`/`load`/`reset`).
16+
- Managing [LocalStack Ephemeral Instances](https://docs.localstack.cloud/user-guide/cloud-sandbox/ephemeral-instance/) (`create`/`list`/`delete`/`logs`).
1817

1918
## Prerequisites
2019

21-
- Dagger CLI installed
22-
- Docker or compatible container runtime
23-
- LocalStack Pro auth token (optional, only for Pro edition)
20+
- [Dagger CLI installed](https://docs.dagger.io/install)
21+
- Docker or a compatible container runtime
22+
- LocalStack Auth Token (required for Pro features, Cloud Pods, and Ephemeral Instances)
2423

25-
## Security
24+
## Installation
2625

27-
This module uses Dagger's secret management system to handle sensitive data like authentication tokens securely. The auth token can be passed using an environment variable:
26+
You can install this module locally to use it in your own Dagger projects or pipelines:
2827

2928
```bash
30-
export LOCALSTACK_AUTH_TOKEN=your-token-here
31-
dagger call start --auth-token=env:LOCALSTACK_AUTH_TOKEN up
29+
dagger install github.com/localstack/localstack-dagger-module
3230
```
3331

34-
The token will be then securely handled by Dagger and never exposed in logs or command output.
32+
You can then call its functions from the Dagger CLI or your Dagger SDK code.
3533

36-
## Inputs
34+
## Usage
3735

38-
### Required Ports
36+
### Start LocalStack Community
3937

40-
| Port | Description | Edition |
41-
|------|-------------|---------|
42-
| 4566 | Main LocalStack endpoint | Community & Pro |
43-
| 443 | HTTPS endpoint | Pro only |
38+
This is the simplest way to start the default LocalStack Community edition.
4439

45-
### Configuration
40+
```bash
41+
dagger -m github.com/localstack/localstack-dagger-module call start up
42+
```
4643

47-
#### `start`
44+
LocalStack will run and be accessible at `localhost:4566` and with any integration that LocalStack supports.
4845

49-
| Input | Description | Default | Example |
50-
|-------|-------------|---------|---------|
51-
| `auth-token` | LocalStack Pro auth token (as Dagger secret) | `None` | `dagger call start --auth-token=env:LOCALSTACK_AUTH_TOKEN` |
52-
| `configuration` | Configuration variables for LocalStack container | `None` | `dagger call start --configuration='DEBUG=1,PERSISTENCE=1'` |
53-
| `docker-sock` | Unix socket path for Docker daemon | `None` | `dagger call start --docker-sock=/var/run/docker.sock` |
54-
| `image-name` | Custom LocalStack image name | `None` | `dagger call start --image-name=localstack/snowflake:latest` |
46+
### Start LocalStack Pro
5547

56-
#### `state`
48+
To use LocalStack Pro features, Cloud Pods, or Ephemeral Instances, you need an Auth Token.
5749

58-
| Input | Description | Default | Example |
59-
|-------|-------------|---------|---------|
60-
| `auth-token` | LocalStack auth token (as Dagger secret, required for save/load) | `None` | `dagger call state --auth-token=env:LOCALSTACK_AUTH_TOKEN` |
61-
| `load` | Name of the LocalStack Cloud Pod to load | `None` | `dagger call state --load=my-pod` |
62-
| `save` | Name of the LocalStack Cloud Pod to save | `None` | `dagger call state --save=my-pod` |
63-
| `reset` | Reset the LocalStack state | `False` | `dagger call state --reset` |
50+
```bash
51+
# 1. Set your LocalStack Pro auth token as an environment variable
52+
export LOCALSTACK_AUTH_TOKEN="your-pro-token"
6453

65-
#### `ephemeral`
54+
# 2. Start LocalStack Pro using the token from the environment
55+
dagger -m github.com/localstack/localstack-dagger-module \
56+
--auth-token=env:LOCALSTACK_AUTH_TOKEN \
57+
call start up
58+
```
6659

67-
| Input | Description | Default | Example |
68-
|-------|-------------|---------|---------|
69-
| `auth-token` | LocalStack Pro auth token (required) | Required | `dagger call ephemeral --auth-token=env:LOCALSTACK_AUTH_TOKEN` |
70-
| `operation` | Operation to perform (`create`/`list`/`delete`/`logs`) | Required | `dagger call ephemeral --operation=create` |
71-
| `name` | Name of the ephemeral instance | Required for `create`/`delete`/`logs` | `dagger call ephemeral --name=my-instance` |
72-
| `lifetime` | Lifetime of the instance in minutes (`create` operation only) | 60 | `dagger call ephemeral --lifetime=120` |
73-
| `auto-load-pod` | Pod configuration to auto-load (`create` operation only) | `None` | `dagger call ephemeral --auto-load-pod=my-pod` |
74-
| `extension-auto-install` | Extension to auto-install (`create` operation only) | `None` | `dagger call ephemeral --extension-auto-install=my-extension --operation=create` |
60+
If the token is invalid or missing when Pro usage is implied, LocalStack might behave unexpectedly or functionality might be limited.
7561

76-
## Usage
62+
### Customizing LocalStack
7763

78-
### Start LocalStack Community Edition
64+
You can pass configuration variables in the following manner:
7965

8066
```bash
81-
# Basic start
82-
dagger call start up
67+
dagger -m github.com/localstack/localstack-dagger-module call start \
68+
--auth-token=env:LOCALSTACK_AUTH_TOKEN \
69+
--configuration='SERVICES=s3' \
70+
up
8371
```
8472

85-
### Start LocalStack Pro Edition
73+
### Mounting Docker Socket
8674

87-
```bash
88-
# Set auth token in environment
89-
export LOCALSTACK_AUTH_TOKEN=your-token-here
75+
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.
76+
77+
```bash
78+
dagger -m github.com/localstack/localstack-dagger-module call start \
79+
--auth-token=env:LOCALSTACK_AUTH_TOKEN \
80+
--docker-sock /var/run/docker.sock \
81+
up
82+
```
83+
84+
### Managing State with Cloud Pods
85+
86+
Cloud pods are persistent state snapshots of your LocalStack instance that can easily be stored, versioned, shared, and restored. Cloud Pods require a LocalStack Auth Token.
87+
88+
```bash
89+
# Set your auth token
90+
export LOCALSTACK_AUTH_TOKEN="your-pro-token"
91+
92+
# Save the current state of your running LocalStack instance to a Cloud Pod
93+
# Assumes you have a running instance started via 'dagger call start ... up'
94+
# And some cloud resources created via an integration
95+
dagger -m github.com/localstack/localstack-dagger-module call state \
96+
--auth-token=env:LOCALSTACK_AUTH_TOKEN \
97+
--save=dagger-test-pod
98+
99+
# Reset the state of the running LocalStack instance
100+
dagger -m github.com/localstack/localstack-dagger-module call state \
101+
--reset
102+
103+
# Load state from a Cloud Pod into your running LocalStack instance
104+
dagger -m github.com/localstack/localstack-dagger-module call state \
105+
--auth-token=env:LOCALSTACK_AUTH_TOKEN \
106+
--load=dagger-test-pod
107+
```
108+
109+
### Managing Ephemeral Instances
110+
111+
Ephemeral Instances allows you to run a LocalStack instance in the cloud. Ephemeral Instances require a LocalStack Pro Auth Token.
90112

91-
# Basic start with auth token from environment
92-
dagger call start --auth-token=env:LOCALSTACK_AUTH_TOKEN up
113+
```bash
114+
# Set your auth token
115+
export LOCALSTACK_AUTH_TOKEN="your-pro-token"
116+
117+
# Create a new Ephemeral Instance in LocalStack Cloud
118+
dagger -m github.com/localstack/localstack-dagger-module call ephemeral \
119+
--auth-token=env:LOCALSTACK_AUTH_TOKEN \
120+
--operation=create \
121+
--name=my-temp-instance \
122+
--lifetime=120
123+
124+
# List active Ephemeral Instances
125+
dagger -m github.com/localstack/localstack-dagger-module call ephemeral \
126+
--auth-token=env:LOCALSTACK_AUTH_TOKEN \
127+
--operation=list
128+
129+
# Get logs for an Ephemeral Instance
130+
dagger -m github.com/localstack/localstack-dagger-module call ephemeral \
131+
--auth-token=env:LOCALSTACK_AUTH_TOKEN \
132+
--operation=logs \
133+
--name=my-temp-instance
134+
135+
# Delete an Ephemeral Instance
136+
dagger -m github.com/localstack/localstack-dagger-module call ephemeral \
137+
--auth-token=env:LOCALSTACK_AUTH_TOKEN \
138+
--operation=delete \
139+
--name=my-temp-instance
93140
```
94141

142+
## Inputs
143+
144+
### `start`
145+
146+
Used to configure and start the main LocalStack service.
147+
148+
| Input | Description | Default | Example |
149+
| --------------- | --------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------------------- |
150+
| `auth-token` | LocalStack Pro auth token (as Dagger `Secret`). Required for Pro features. | `None` | `dagger call start --auth-token=env:LOCALSTACK_AUTH_TOKEN` |
151+
| `configuration` | Comma-separated `KEY=VALUE` pairs for LocalStack environment variables. | `None` | `dagger call start --configuration='DEBUG=1,PERSISTENCE=1'` |
152+
| `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` |
153+
| `image-name` | Custom LocalStack Docker image name and tag. | `localstack/localstack:latest` | `dagger call start --image-name=localstack/snowflake:latest` |
154+
155+
### `state`
156+
157+
Used to manage the state of a running LocalStack instance using Cloud Pods (Pro only).
158+
159+
| Input | Description | Default | Example |
160+
| ------------ | ------------------------------------------------------------------------------------ | --------- | ------------------------------------------------ |
161+
| `auth-token` | LocalStack Pro Auth Token (as Dagger `Secret`). Required for `save` and `load`. | `None` | `dagger call state --auth-token=env:LOCALSTACK_AUTH_TOKEN` |
162+
| `load` | Name of the LocalStack Cloud Pod to load into the running instance. | `None` | `dagger call state --load=my-pod` |
163+
| `save` | Name under which to save the current state as a LocalStack Cloud Pod. | `None` | `dagger call state --save=my-pod` |
164+
| `reset` | If `true`, resets the state of the running LocalStack instance. | `False` | `dagger call state --reset` |
165+
166+
### `ephemeral`
167+
168+
Used to manage LocalStack Ephemeral Instances in LocalStack Cloud (Pro only).
169+
170+
| Input | Description | Default | Example |
171+
| ------------------------ | ---------------------------------------------------------------------------------------------------------- | --------- | -------------------------------------------------------- |
172+
| `auth-token` | LocalStack Pro Auth Token (as Dagger `Secret`). Required for all operations. | Required | `dagger call ephemeral --auth-token=env:LOCALSTACK_AUTH_TOKEN` |
173+
| `operation` | Action to perform: `create`, `list`, `delete`, `logs`. | Required | `dagger call ephemeral --operation=create` |
174+
| `name` | Name of the ephemeral instance. Required for `create`, `delete`, `logs`. | `None` | `dagger call ephemeral --name=my-instance` |
175+
| `lifetime` | Lifetime of the instance in minutes (only for `create` operation). | `60` | `dagger call ephemeral --lifetime=120` |
176+
| `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` |
177+
| `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` |
178+
95179
## Development
96180

97-
To develop this module:
181+
To contribute or make local changes to this module:
182+
183+
1. Clone the repository:
184+
```bash
185+
git clone https://github.com/localstack/localstack-dagger-module.git
186+
cd localstack-dagger-module
187+
```
188+
2. Run `dagger develop` to set up the development environment.
189+
3. Make your changes, typically within the Dagger module source files (e.g., in `.dagger/src/`).
190+
4. Test your changes locally using `dagger call` or `dagger test` as described in the sections above.
191+
192+
## License
98193

99-
1. Clone the repository
100-
2. Run `dagger develop` to set up the development environment
101-
3. Make your changes in `.dagger/src/localstack_dagger_module/main.py`
102-
4. Test your changes using the commands above
194+
This project is licensed under the Apache License 2.0. See the [LICENSE](./LICENSE) file for details.

0 commit comments

Comments
 (0)