diff --git a/astro.config.mjs b/astro.config.mjs index 948833d6..b10c47c6 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -389,6 +389,13 @@ export default defineConfig({ collapsed: true, items: [{ autogenerate: { directory: '/aws/getting-started' } }], }, + { + label: 'Quick Start Library', + collapsed: true, + items: [ + { autogenerate: { directory: '/aws/quickstart-library' } }, + ], + }, { label: 'Local AWS Services', slug: 'aws/services', @@ -604,7 +611,8 @@ export default defineConfig({ items: [ { autogenerate: { - directory: '/aws/customization/integrations/extensions', + directory: + '/aws/customization/integrations/extensions', }, }, { @@ -619,7 +627,8 @@ export default defineConfig({ items: [ { autogenerate: { - directory: '/aws/customization/integrations/localstack-sdks', + directory: + '/aws/customization/integrations/localstack-sdks', }, }, ], @@ -630,7 +639,8 @@ export default defineConfig({ items: [ { autogenerate: { - directory: '/aws/customization/integrations/app-frameworks', + directory: + '/aws/customization/integrations/app-frameworks', }, }, ], @@ -641,7 +651,8 @@ export default defineConfig({ items: [ { autogenerate: { - directory: '/aws/customization/integrations/testing', + directory: + '/aws/customization/integrations/testing', }, }, ], diff --git a/public/_redirects b/public/_redirects index 06a227af..036550a0 100644 --- a/public/_redirects +++ b/public/_redirects @@ -397,7 +397,8 @@ /tutorials/replicate-aws-resources-localstack-extension/ /aws/tutorials/replicate-aws-resources-localstack-extension/ 301 /user-guide/tools/localstack-sdk/python/ /aws/customization/integrations/localstack-sdks/python-sdk/ 301 /user-guide/lambda-tools/hot-reloading/ /aws/developer-tools/lambda-tools/hot-reloading/ 301 -/getting-started/quickstart/ /aws/getting-started/quickstart/ 301 +/getting-started/quickstart/ /aws/getting-started/local-development/ 301 +/aws/getting-started/quickstart/ /aws/getting-started/local-development/ 301 /overview/ /aws/ 301 /user-guide/aws/glue/ /aws/services/glue/ 301 /getting-started/ /aws/getting-started/ 301 @@ -804,7 +805,8 @@ /tutorials/replicate-aws-resources-localstack-extension /aws/tutorials/replicate-aws-resources-localstack-extension/ 301 /user-guide/tools/localstack-sdk/python /aws/customization/integrations/localstack-sdks/python-sdk/ 301 /user-guide/lambda-tools/hot-reloading /aws/developer-tools/lambda-tools/hot-reloading/ 301 -/getting-started/quickstart /aws/getting-started/quickstart/ 301 +/getting-started/quickstart /aws/getting-started/local-development/ 301 +/aws/getting-started/quickstart /aws/getting-started/local-development/ 301 /overview /aws/ 301 /user-guide/aws/glue /aws/services/glue/ 301 /getting-started /aws/getting-started/ 301 diff --git a/public/images/aws/app-inspector-operations.jpg b/public/images/aws/app-inspector-operations.jpg new file mode 100644 index 00000000..d2820d1e Binary files /dev/null and b/public/images/aws/app-inspector-operations.jpg differ diff --git a/public/images/aws/dynamodb-resource-browser.jpg b/public/images/aws/dynamodb-resource-browser.jpg new file mode 100644 index 00000000..a52bd6a9 Binary files /dev/null and b/public/images/aws/dynamodb-resource-browser.jpg differ diff --git a/public/images/aws/export-cloud-pod-web-app.jpg b/public/images/aws/export-cloud-pod-web-app.jpg new file mode 100644 index 00000000..daaa8277 Binary files /dev/null and b/public/images/aws/export-cloud-pod-web-app.jpg differ diff --git a/public/images/aws/lambda-resource-browser.jpg b/public/images/aws/lambda-resource-browser.jpg new file mode 100644 index 00000000..58784dd0 Binary files /dev/null and b/public/images/aws/lambda-resource-browser.jpg differ diff --git a/public/images/aws/load-state-from-pod.jpg b/public/images/aws/load-state-from-pod.jpg new file mode 100644 index 00000000..4453bf53 Binary files /dev/null and b/public/images/aws/load-state-from-pod.jpg differ diff --git a/public/images/aws/localstack-resource-browser.png b/public/images/aws/localstack-resource-browser.png new file mode 100644 index 00000000..a228b2b7 Binary files /dev/null and b/public/images/aws/localstack-resource-browser.png differ diff --git a/public/images/aws/running-instance-sidebar.jpg b/public/images/aws/running-instance-sidebar.jpg new file mode 100644 index 00000000..85213070 Binary files /dev/null and b/public/images/aws/running-instance-sidebar.jpg differ diff --git a/public/images/aws/stack-overview.jpg b/public/images/aws/stack-overview.jpg new file mode 100644 index 00000000..9ff1e52e Binary files /dev/null and b/public/images/aws/stack-overview.jpg differ diff --git a/public/images/aws/verify-cloud-pod-save.jpg b/public/images/aws/verify-cloud-pod-save.jpg new file mode 100644 index 00000000..053318c1 Binary files /dev/null and b/public/images/aws/verify-cloud-pod-save.jpg differ diff --git a/public/js/icon-loader.js b/public/js/icon-loader.js index e2d20a34..04705564 100644 --- a/public/js/icon-loader.js +++ b/public/js/icon-loader.js @@ -5,6 +5,7 @@ const iconMappings = { Welcome: 'cube-icon', 'Getting Started': 'rocket-icon', + 'Quick Start Library': 'lightning-icon', 'Local AWS Services': 'cube-icon', 'Local Azure Services': 'cube-icon', Features: 'cube-icon', diff --git a/scripts/redirects/redirects_config.json b/scripts/redirects/redirects_config.json index 6f358056..6ed8fdf0 100644 --- a/scripts/redirects/redirects_config.json +++ b/scripts/redirects/redirects_config.json @@ -1975,7 +1975,12 @@ }, { "old_link": "/getting-started/quickstart/", - "new_link": "/aws/getting-started/quickstart", + "new_link": "/aws/getting-started/local-development/", + "status_code": 301 + }, + { + "old_link": "/aws/getting-started/quickstart/", + "new_link": "/aws/getting-started/local-development/", "status_code": 301 }, { diff --git a/src/assets/images/lightning.svg b/src/assets/images/lightning.svg new file mode 100644 index 00000000..eadf570e --- /dev/null +++ b/src/assets/images/lightning.svg @@ -0,0 +1,3 @@ + + + diff --git a/src/content/docs/aws/developer-tools/aws-replicator/index.mdx b/src/content/docs/aws/developer-tools/aws-replicator/index.mdx index f05ff9a3..ea880b3d 100644 --- a/src/content/docs/aws/developer-tools/aws-replicator/index.mdx +++ b/src/content/docs/aws/developer-tools/aws-replicator/index.mdx @@ -29,7 +29,7 @@ A valid `LOCALSTACK_AUTH_TOKEN` must be configured to start the LocalStack for A :::note The Replicator is in limited preview and is available from LocalStack CLI version 4.2.0. -If you encounter issues, update your [LocalStack CLI](/aws/getting-started/installation/#updating-localstack-cli). +If you encounter issues, update your [LocalStack CLI](/aws/getting-started/installation/#update-localstack-cli). ::: ### Retrieve credentials to access AWS @@ -85,7 +85,7 @@ The replication type and explore strategy are independent: `replication_type` se The Replicator CLI is part of the LocalStack CLI. -Follow the [installation instructions](/aws/getting-started/installation/#installing-localstack-cli) to set it up. +Follow the [installation instructions](/aws/getting-started/installation/#install-localstack-cli) to set it up. To start a replication job, get the ARN of the resource to replicate. Then, trigger the job using the command: diff --git a/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md b/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md index 1c00d011..0dcfaf16 100644 --- a/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md +++ b/src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md @@ -87,7 +87,7 @@ If you have created a Cloud Pod from an older version of LocalStack, you need to ## Ephemeral Instances CLI -The Ephemeral Instances CLI is included in the [LocalStack CLI installation](/aws/getting-started/installation/#installing-localstack-cli), so no additional installations are needed to start using it. +The Ephemeral Instances CLI is included in the [LocalStack CLI installation](/aws/getting-started/installation/#install-localstack-cli), so no additional installations are needed to start using it. If you're a licensed user, setting the `LOCALSTACK_AUTH_TOKEN` as an environment variable is recommended to access all features of the Ephemeral Instances CLI. Access the Ephemeral Instances CLI by running the `localstack ephemeral` command from your terminal. diff --git a/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md b/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md index 184fac03..73260656 100644 --- a/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md +++ b/src/content/docs/aws/developer-tools/running-localstack/localstack-cli.md @@ -3,18 +3,254 @@ title: LocalStack CLI description: Reference guide for LocalStack CLI commands, options, and usage. template: doc sidebar: - order: 10 -tags: ["Hobby"] + order: 10 +tags: ['Hobby'] --- +import { Tabs, TabItem } from '@astrojs/starlight/components'; +import { LinkButton, Code } from '@astrojs/starlight/components'; +import { LOCALSTACK_AWS_VERSION } from 'astro:env/server'; + ## Introduction The LocalStack Command Line Interface (CLI) is a tool for starting, managing, and configuring your LocalStack container. It provides convenience features to interact with LocalStack features like Cloud Pods, Extensions, State Management, and more. -To install the LocalStack CLI, follow the [installation guide](/aws/getting-started/installation/#installing-localstack-cli). +:::caution +The LocalStack CLI is deprecated and will be removed in a future version. +Please use [lstk](/aws/developer-tools/running-localstack/lstk/) instead. +::: + +## Installation + + + + + +You can download the pre-built binary for your architecture using the link below: + + + {' '} + x86-64 + + + ARM64 + + +or use the curl commands below: + +For x86-64: + + + +For ARM64: + + + +Then extract the LocalStack CLI from the terminal: + + + +
+Alternative: Homebrew on Linux + +If you are using [Homebrew for Linux](https://docs.brew.sh/Homebrew-on-Linux), you can install the LocalStack CLI directly from our official LocalStack tap: + +```bash +brew install localstack/tap/localstack-cli +``` + +
+ + + + + +You can install the LocalStack CLI using Brew directly from our official LocalStack tap: + +```bash +brew install localstack/tap/localstack-cli +``` + +
+Alternative: Binary Download + +You may download the binary for your architecture using the link below: + + + {' '} + Intel (AMD64) + + +or use the following curl command: + + + +Then extract the LocalStack CLI from the terminal: + + + +
+ + + + +You can download the pre-built binary for your architecture using the link below: + + + {' '} + Intel (AMD64) + + +Then extract the archive and execute the binary in Powershell. + + + + + +If you cannot use the binary releases of LocalStack, you can install the Python distribution. + +Please make sure to install the following before moving ahead: + +- [Python](https://docs.python.org/3/using/index.html) +- [pip](https://pip.pypa.io/en/stable/installation/) + +Next install the LocalStack CLI in your Python environment by running: + +```bash +python3 -m pip install --upgrade localstack +``` + +:::note +To download a specific version of LocalStack, replace `` with the required version from [changelog page](/aws/changelog). + +```bash +python3 -m pip install localstack== +``` + +::: + +:::tip[MacOS Sierra?] +If you have problems with permissions in MacOS X Sierra, install with: + +```bash +python3 -m pip install --user localstack +``` + +::: + +:::danger +Do not use `sudo` or the `root` user when starting LocalStack. +It should be installed and started entirely under a local non-root user. +::: + + + + +### Starting LocalStack + +To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal: + + + +You are all set! + +:::note +To start LocalStack, you must first [set up your auth token](/aws/getting-started/auth-token). +::: + +Once you've set up your auth token, you can start LocalStack with the following command: + +```bash +localstack start # start localstack in background with -d flag +``` + +{/_ prettier-ignore _/} + + + +### Updating LocalStack CLI + +The LocalStack CLI allows you to easily update the different components of LocalStack. +To check the various options available for updating, run: + +```bash +localstack update --help +``` + +```bash +Usage: localstack update [OPTIONS] COMMAND [ARGS]... + + Update different LocalStack components. + +Options: + -h, --help Show this message and exit. + +Commands: + all Update all LocalStack components + docker-images Update docker images LocalStack depends on + localstack-cli Update LocalStack CLI +``` :::note +Updating the LocalStack CLI using `localstack update localstack-cli` and `localstack update all` will work only if it was installed from the Python distribution. +If it was installed using the pre-built binary or via Brew, please run the installation steps again to update to the latest version. +::: + +:::note +This documentation below was auto-generated from LocalStack CLI version `LocalStack CLI 2026.4.0`. + [`lstk`](/aws/developer-tools/running-localstack/lstk/) is our new Go-based CLI with an interactive terminal UI for lifecycle (`start`, `stop`), monitoring (`status`, `logs`), storage (`snapshot`), and more. ::: @@ -22,12 +258,12 @@ To install the LocalStack CLI, follow the [installation guide](/aws/getting-star The following global options are available for the `localstack` CLI: -| Option | Description | -|--------|-------------| -| `-v`, `--version` | Show the version and exit | -| `-d`, `--debug` | Enable CLI debugging mode | +| Option | Description | +| ---------------------- | ----------------------------- | +| `-v`, `--version` | Show the version and exit | +| `-d`, `--debug` | Enable CLI debugging mode | | `-p`, `--profile TEXT` | Set the configuration profile | -| `-h`, `--help` | Show help message and exit | +| `-h`, `--help` | Show help message and exit | ## Commands @@ -791,8 +1027,6 @@ Commands: #### `license activate` - - ```bash Usage: localstack license activate [OPTIONS] @@ -802,8 +1036,6 @@ Options: #### `license info` - - ```bash Usage: localstack license info [OPTIONS] diff --git a/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx b/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx index 87feb679..32b6d479 100644 --- a/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx +++ b/src/content/docs/aws/developer-tools/running-localstack/mcp-server.mdx @@ -33,7 +33,15 @@ You must include it in the `env` block of your configuration. You can get your Auth Token from the [LocalStack Web App](https://app.localstack.cloud). ::: -Choose your MCP client below for setup instructions. +The quickest way to get started with the MCP server is to use the interactive setup wizard: + +```bash +npx -y @localstack/localstack-mcp-server init +``` + +The wizard detects your installed clients, asks how you want to run the server, and writes the configuration for you. You need a valid [Auth Token](/aws/getting-started/auth-token/) to configure the server. + +For manual setup of the MCP server, choose your MCP client below for setup instructions. @@ -171,10 +179,10 @@ Refer to your client's documentation for the exact location of its MCP configura By default the MCP server connects to `http://localhost:4566`. If your LocalStack instance runs on a different host or port, set the following environment variables in the `env` block: -| Variable | Default | Description | -|---|---|---| +| Variable | Default | Description | +| --------------------- | ----------- | ----------------------------------- | | `LOCALSTACK_HOSTNAME` | `localhost` | Hostname of the LocalStack instance | -| `LOCALSTACK_PORT` | `4566` | Port of the LocalStack instance | +| `LOCALSTACK_PORT` | `4566` | Port of the LocalStack instance | You can also pass any [LocalStack configuration variable](/aws/customization/configuration-options/) through the `env` block. These are forwarded to the container when the `localstack-management` tool starts it. @@ -204,11 +212,11 @@ Each tool runs pre-flight checks (verifying the CLI is available, the container Manage the LocalStack runtime lifecycle for both the AWS emulator and the Snowflake emulator. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `start` \| `stop` \| `restart` \| `status` | Yes | The operation to perform | -| `service` | `aws` \| `snowflake` | No | The stack to manage (default: `aws`) | -| `envVars` | `Record` | No | Extra environment variables passed on `start` | +| Parameter | Type | Required | Description | +| --------- | ------------------------------------------ | -------- | --------------------------------------------- | +| `action` | `start` \| `stop` \| `restart` \| `status` | Yes | The operation to perform | +| `service` | `aws` \| `snowflake` | No | The stack to manage (default: `aws`) | +| `envVars` | `Record` | No | Extra environment variables passed on `start` | **Example prompts:** @@ -220,17 +228,17 @@ Manage the LocalStack runtime lifecycle for both the AWS emulator and the Snowfl Deploy or destroy infrastructure on LocalStack using CDK, Terraform, SAM, or CloudFormation. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `deploy` \| `destroy` \| `create-stack` \| `delete-stack` | Yes | The deployment operation | -| `projectType` | `cdk` \| `terraform` \| `sam` \| `auto` | No | Framework to use (default: `auto`, detected from project files) | -| `directory` | `string` | Yes (for `deploy`/`destroy`) | Path to the project directory | -| `variables` | `Record` | No | Variables passed as Terraform `-var` flags, CDK `--context` values, or SAM `--parameter-overrides` | -| `stackName` | `string` | Yes (for `create-stack`/`delete-stack`) | CloudFormation/SAM stack name | -| `templatePath` | `string` | No | Path to a CloudFormation/SAM template | -| `s3Bucket` | `string` | No | S3 bucket for SAM deployments (if omitted, SAM uses `--resolve-s3`) | -| `resolveS3` | `boolean` | No | For SAM deployments, whether to use `--resolve-s3` when no `s3Bucket` is provided | -| `saveParams` | `boolean` | No | For SAM deployments, whether to persist resolved parameters to `samconfig.toml` | +| Parameter | Type | Required | Description | +| -------------- | --------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `action` | `deploy` \| `destroy` \| `create-stack` \| `delete-stack` | Yes | The deployment operation | +| `projectType` | `cdk` \| `terraform` \| `sam` \| `auto` | No | Framework to use (default: `auto`, detected from project files) | +| `directory` | `string` | Yes (for `deploy`/`destroy`) | Path to the project directory | +| `variables` | `Record` | No | Variables passed as Terraform `-var` flags, CDK `--context` values, or SAM `--parameter-overrides` | +| `stackName` | `string` | Yes (for `create-stack`/`delete-stack`) | CloudFormation/SAM stack name | +| `templatePath` | `string` | No | Path to a CloudFormation/SAM template | +| `s3Bucket` | `string` | No | S3 bucket for SAM deployments (if omitted, SAM uses `--resolve-s3`) | +| `resolveS3` | `boolean` | No | For SAM deployments, whether to use `--resolve-s3` when no `s3Bucket` is provided | +| `saveParams` | `boolean` | No | For SAM deployments, whether to persist resolved parameters to `samconfig.toml` | **Example prompts:** @@ -248,13 +256,13 @@ The `create-stack` and `delete-stack` actions run `awslocal` inside the LocalSta Analyze LocalStack logs to find errors, summarize API activity, or inspect raw output. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `analysisType` | `summary` \| `errors` \| `requests` \| `logs` | No | Type of analysis (default: `summary`) | -| `lines` | `number` | No | Number of log lines to fetch (default: `2000`) | -| `service` | `string` | No | Filter by AWS service name | -| `operation` | `string` | No | Filter by API operation (used with `service` in `requests` mode) | -| `filter` | `string` | No | Keyword filter (used with `logs` mode only) | +| Parameter | Type | Required | Description | +| -------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------- | +| `analysisType` | `summary` \| `errors` \| `requests` \| `logs` | No | Type of analysis (default: `summary`) | +| `lines` | `number` | No | Number of log lines to fetch (default: `2000`) | +| `service` | `string` | No | Filter by AWS service name | +| `operation` | `string` | No | Filter by API operation (used with `service` in `requests` mode) | +| `filter` | `string` | No | Keyword filter (used with `logs` mode only) | **Example prompts:** @@ -266,10 +274,10 @@ Analyze LocalStack logs to find errors, summarize API activity, or inspect raw o Configure IAM enforcement and generate IAM policies from access denials in the logs. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `set-mode` \| `analyze-policies` \| `get-status` | Yes | The operation to perform | -| `mode` | `ENFORCED` \| `SOFT_MODE` \| `DISABLED` | Yes (for `set-mode`) | IAM enforcement level | +| Parameter | Type | Required | Description | +| --------- | ------------------------------------------------ | -------------------- | ------------------------ | +| `action` | `set-mode` \| `analyze-policies` \| `get-status` | Yes | The operation to perform | +| `mode` | `ENFORCED` \| `SOFT_MODE` \| `DISABLED` | Yes (for `set-mode`) | IAM enforcement level | **Example prompts:** @@ -281,21 +289,21 @@ Configure IAM enforcement and generate IAM policies from access denials in the l Inject faults and network latency into LocalStack services to test application resilience. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `inject-faults` \| `add-fault-rule` \| `remove-fault-rule` \| `get-faults` \| `clear-all-faults` \| `inject-latency` \| `get-latency` \| `clear-latency` | Yes | The chaos operation | -| `rules` | `Array` | Yes (for `inject-faults`, `add-fault-rule`, `remove-fault-rule`) | Fault rules to inject/modify | -| `latency_ms` | `number` | Yes (for `inject-latency`) | Latency in milliseconds to add to all requests | +| Parameter | Type | Required | Description | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- | +| `action` | `inject-faults` \| `add-fault-rule` \| `remove-fault-rule` \| `get-faults` \| `clear-all-faults` \| `inject-latency` \| `get-latency` \| `clear-latency` | Yes | The chaos operation | +| `rules` | `Array` | Yes (for `inject-faults`, `add-fault-rule`, `remove-fault-rule`) | Fault rules to inject/modify | +| `latency_ms` | `number` | Yes (for `inject-latency`) | Latency in milliseconds to add to all requests | Each **fault rule** can include: -| Field | Type | Description | -|---|---|---| -| `service` | `string` | Target AWS service (e.g., `s3`, `lambda`) | -| `region` | `string` | Target region (e.g., `us-east-1`) | -| `operation` | `string` | Target API operation (e.g., `PutObject`) | -| `probability` | `number` (0-1) | Probability of the fault triggering | -| `error` | `{ statusCode?: number, code?: string }` | Error response to return | +| Field | Type | Description | +| ------------- | ---------------------------------------- | ----------------------------------------- | +| `service` | `string` | Target AWS service (e.g., `s3`, `lambda`) | +| `region` | `string` | Target region (e.g., `us-east-1`) | +| `operation` | `string` | Target API operation (e.g., `PutObject`) | +| `probability` | `number` (0-1) | Probability of the fault triggering | +| `error` | `{ statusCode?: number, code?: string }` | Error response to return | **Example prompts:** @@ -307,10 +315,10 @@ Each **fault rule** can include: Save, load, and manage LocalStack state snapshots using [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods/). -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `save` \| `load` \| `delete` \| `reset` | Yes | The state management operation | -| `pod_name` | `string` | Yes (for `save`/`load`/`delete`) | Name of the Cloud Pod (alphanumeric, dots, hyphens, underscores; max 128 characters) | +| Parameter | Type | Required | Description | +| ---------- | --------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------ | +| `action` | `save` \| `load` \| `delete` \| `reset` | Yes | The state management operation | +| `pod_name` | `string` | Yes (for `save`/`load`/`delete`) | Name of the Cloud Pod (alphanumeric, dots, hyphens, underscores; max 128 characters) | **Example prompts:** @@ -322,9 +330,9 @@ Save, load, and manage LocalStack state snapshots using [Cloud Pods](/aws/develo Execute AWS CLI commands inside the running LocalStack container via `awslocal`. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `command` | `string` | Yes | The AWS CLI command to run (without the `aws` or `awslocal` prefix) | +| Parameter | Type | Required | Description | +| --------- | -------- | -------- | ------------------------------------------------------------------- | +| `command` | `string` | Yes | The AWS CLI command to run (without the `aws` or `awslocal` prefix) | **Example prompts:** @@ -339,11 +347,11 @@ If a command fails due to a service not being emulated, the tool returns a link Install, uninstall, list, and discover [LocalStack Extensions](/aws/customization/integrations/extensions/) from the marketplace. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `list` \| `install` \| `uninstall` \| `available` | Yes | The extensions operation | -| `name` | `string` | Yes (for `install`/`uninstall`) | Extension package name (e.g., `localstack-extension-typedb`) | -| `source` | `string` | No | Git URL to install from (alternative to `name`) | +| Parameter | Type | Required | Description | +| --------- | ------------------------------------------------- | ------------------------------- | ------------------------------------------------------------ | +| `action` | `list` \| `install` \| `uninstall` \| `available` | Yes | The extensions operation | +| `name` | `string` | Yes (for `install`/`uninstall`) | Extension package name (e.g., `localstack-extension-typedb`) | +| `source` | `string` | No | Git URL to install from (alternative to `name`) | **Example prompts:** @@ -360,14 +368,14 @@ After installing or uninstalling an extension, the tool automatically restarts L Manage cloud-hosted [Ephemeral Instances](/aws/developer-tools/cloud-sandbox/ephemeral-instances/) for remote LocalStack testing workflows. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `create` \| `list` \| `logs` \| `delete` | Yes | The ephemeral instance operation | -| `name` | `string` | Yes (for `create`/`logs`/`delete`) | Instance name | -| `lifetime` | `number` | No | Lifetime in minutes for the instance (only for `create`) | -| `extension` | `string` | No | Extension package to preload on the instance (only for `create`) | -| `cloudPod` | `string` | No | Cloud Pod name to initialize state from (only for `create`) | -| `envVars` | `Record` | No | Extra environment variables for the instance (only for `create`) | +| Parameter | Type | Required | Description | +| ----------- | ---------------------------------------- | ---------------------------------- | ---------------------------------------------------------------- | +| `action` | `create` \| `list` \| `logs` \| `delete` | Yes | The ephemeral instance operation | +| `name` | `string` | Yes (for `create`/`logs`/`delete`) | Instance name | +| `lifetime` | `number` | No | Lifetime in minutes for the instance (only for `create`) | +| `extension` | `string` | No | Extension package to preload on the instance (only for `create`) | +| `cloudPod` | `string` | No | Cloud Pod name to initialize state from (only for `create`) | +| `envVars` | `Record` | No | Extra environment variables for the instance (only for `create`) | **Example prompts:** @@ -380,10 +388,10 @@ Manage cloud-hosted [Ephemeral Instances](/aws/developer-tools/cloud-sandbox/eph Search the LocalStack documentation to find guides, API references, and configuration details. -| Parameter | Type | Required | Description | -|---|---|---|---| -| `query` | `string` | Yes | The search query | -| `limit` | `number` | No | Maximum number of results to return (default: `5`, max: `10`) | +| Parameter | Type | Required | Description | +| --------- | -------- | -------- | ------------------------------------------------------------- | +| `query` | `string` | Yes | The search query | +| `limit` | `number` | No | Maximum number of results to return (default: `5`, max: `10`) | **Example prompts:** @@ -394,15 +402,15 @@ Search the LocalStack documentation to find guides, API references, and configur Execute SQL queries and commands against the [LocalStack Snowflake emulator](/snowflake/) using the Snowflake CLI (`snow`). -| Parameter | Type | Required | Description | -|---|---|---|---| -| `action` | `execute` \| `check-connection` | Yes | The operation to perform | -| `query` | `string` | Yes (for `execute`, if `file_path` not provided) | SQL query to execute | -| `file_path` | `string` | Yes (for `execute`, if `query` not provided) | Absolute path to a `.sql` file to execute | -| `database` | `string` | No | Snowflake database context | -| `schema` | `string` | No | Snowflake schema context | -| `warehouse` | `string` | No | Snowflake warehouse to use | -| `role` | `string` | No | Snowflake role to use | +| Parameter | Type | Required | Description | +| ----------- | ------------------------------- | ------------------------------------------------ | ----------------------------------------- | +| `action` | `execute` \| `check-connection` | Yes | The operation to perform | +| `query` | `string` | Yes (for `execute`, if `file_path` not provided) | SQL query to execute | +| `file_path` | `string` | Yes (for `execute`, if `query` not provided) | Absolute path to a `.sql` file to execute | +| `database` | `string` | No | Snowflake database context | +| `schema` | `string` | No | Snowflake schema context | +| `warehouse` | `string` | No | Snowflake warehouse to use | +| `role` | `string` | No | Snowflake role to use | **Example prompts:** @@ -421,31 +429,31 @@ Once your MCP client is configured, verify the setup by opening a conversation w **1. Start LocalStack** -> *"Start my LocalStack container."* +> _"Start my LocalStack container."_ The agent uses the `localstack-management` tool to start the container and confirms the status. **2. Deploy infrastructure** -> *"Deploy my CDK project in the `./my-app` directory."* +> _"Deploy my CDK project in the `./my-app` directory."_ The agent detects the framework, runs `cdklocal bootstrap` and `cdklocal deploy`, and returns the stack outputs. **3. Verify resources** -> *"List the Lambda functions and DynamoDB tables that were created."* +> _"List the Lambda functions and DynamoDB tables that were created."_ The agent runs `awslocal` commands inside the container and returns the results. **4. Analyze logs** -> *"Check the LocalStack logs for any errors."* +> _"Check the LocalStack logs for any errors."_ The agent fetches recent logs and highlights any errors or warnings. **5. Save state** -> *"Save a Cloud Pod named `my-checkpoint`."* +> _"Save a Cloud Pod named `my-checkpoint`."_ The agent persists the current LocalStack state so you can restore it later. @@ -453,13 +461,13 @@ The agent persists the current LocalStack state so you can restore it later. The following environment variables can be set in the `env` block of your MCP configuration: -| Variable | Default | Description | -|---|---|---| -| `LOCALSTACK_AUTH_TOKEN` (**required**) | None | Your LocalStack Auth Token. Required for all MCP server tools. | -| `LOCALSTACK_HOSTNAME` | `localhost` | Hostname of the LocalStack instance | -| `LOCALSTACK_PORT` | `4566` | Port of the LocalStack instance | -| `MAIN_CONTAINER_NAME` | `localstack-main` | Name of the LocalStack Docker container | -| `MCP_ANALYTICS_DISABLED` | `0` | Set to `1` to disable MCP analytics | +| Variable | Default | Description | +| -------------------------------------- | ----------------- | -------------------------------------------------------------- | +| `LOCALSTACK_AUTH_TOKEN` (**required**) | None | Your LocalStack Auth Token. Required for all MCP server tools. | +| `LOCALSTACK_HOSTNAME` | `localhost` | Hostname of the LocalStack instance | +| `LOCALSTACK_PORT` | `4566` | Port of the LocalStack instance | +| `MAIN_CONTAINER_NAME` | `localstack-main` | Name of the LocalStack Docker container | +| `MCP_ANALYTICS_DISABLED` | `0` | Set to `1` to disable MCP analytics | Any [LocalStack configuration variable](/aws/customization/configuration-options/) can also be passed through the `env` block. These are forwarded to the container when the `localstack-management` tool starts it. diff --git a/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx b/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx index c4813cdc..c6b460cf 100644 --- a/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx +++ b/src/content/docs/aws/developer-tools/security-testing/custom-tls-certificates.mdx @@ -30,7 +30,7 @@ They all can be summarised as: ## Creating a custom docker image -If you run LocalStack in a docker container (which includes using [the CLI](/aws/getting-started/installation/#installing-localstack-cli), [docker](/aws/getting-started/installation/#docker), [docker-compose](/aws/getting-started/installation/#docker-compose), or [helm](/aws/customization/kubernetes/deploy-helm-chart)), to include a custom TLS root certificate a new docker image should be created. +If you run LocalStack in a docker container (which includes using [the CLI](/aws/getting-started/installation/#install-localstack-cli), [docker](/aws/getting-started/installation/#docker-compose), [docker-compose](/aws/getting-started/installation/#docker-compose), or [helm](/aws/customization/kubernetes/deploy-helm-chart)), to include a custom TLS root certificate a new docker image should be created. Create a `Dockerfile` containing the following commands: diff --git a/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx b/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx index 14b43118..d85aff37 100644 --- a/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx +++ b/src/content/docs/aws/developer-tools/snapshots/cloud-pods.mdx @@ -28,7 +28,7 @@ You can save and load the persistent state of Cloud Pods, you can use the [Cloud LocalStack provides a remote storage backend that can be used to store the state of your running application and share it with your team members. You can interact with the Cloud Pods over the storage backend via the LocalStack Web Application. -Cloud Pods CLI is included in the [LocalStack CLI installation](/aws/getting-started/installation/#installing-localstack-cli), so there's no need for additional installations to begin using it. +Cloud Pods CLI is included in the [LocalStack CLI installation](/aws/getting-started/installation/#install-localstack-cli), so there's no need for additional installations to begin using it. If you're a licensed user, we suggest setting the `LOCALSTACK_AUTH_TOKEN` as an environment variable. This enables you to access the complete range of LocalStack Cloud Pods features. @@ -451,7 +451,7 @@ localstack pod list s3-storage-aws :::note Full S3 remotes support is available in the CLI from version 3.2.0. -If you experience any difficulties, update your [LocalStack CLI](/aws/getting-started/installation/#updating-localstack-cli). +If you experience any difficulties, update your [LocalStack CLI](/aws/getting-started/installation/#update-localstack-cli). ::: ### ORAS remote storage diff --git a/src/content/docs/aws/getting-started/ai-workflows.mdx b/src/content/docs/aws/getting-started/ai-workflows.mdx new file mode 100644 index 00000000..091267b3 --- /dev/null +++ b/src/content/docs/aws/getting-started/ai-workflows.mdx @@ -0,0 +1,108 @@ +--- +title: AI & Agent Workflows +description: Use LocalStack with AI coding assistants, MCP clients, and agent-driven infrastructure workflows. +template: doc +sidebar: + order: 5 +--- + +## Introduction + +LocalStack gives AI coding assistants a local AWS-compatible environment to work against. Instead of letting an agent experiment in a real AWS account, you can ask it to create infrastructure, deploy code, inspect logs, and test resources in LocalStack first. + +This is useful when you want to: + +- Prototype AWS applications & infrastructure code from natural language prompts. +- Validate AI-generated Terraform, CDK, or AWS CLI commands before using a cloud account. +- Give an AI assistant a safe place to inspect resources, debug logs, and iterate on deployments. +- Use reusable agent instructions for LocalStack-aware infrastructure workflows. + +## Common workflows + +There are three common ways to use LocalStack in AI-assisted development: + +- Use the [LocalStack MCP Server](/aws/tooling/mcp-server/) when your AI assistant supports MCP clients such as Cursor, Claude, Codex, or OpenCode. +- Use [LocalStack Skills](https://github.com/localstack/skills) when you want reusable agent instructions for deploying and testing AWS architectures against LocalStack. +- Use LocalStack with `tflocal`, `cdklocal`, or `awslocal` when you want the agent to generate infrastructure code or commands that you review and run locally. + +You do not need all three approaches to get started. If your editor supports MCP, start with the LocalStack MCP Server. Or, you can use Skills if you want reusable agent instructions. If not, ask your assistant to generate Terraform, CDK, or AWS CLI steps and run them with LocalStack's local wrappers. + +## Quick Setup + +LocalStack has provided an [`agents.md`](https://blog.localstack.cloud/ai/agents.md) file that provides the full instructions for your AI agent to get started with LocalStack, including how to configure the MCP server and LocalStack Skills. Details can be found at our [agents landing page](https://blog.localstack.cloud/ai/) or you can copy and paste the instructions below into your AI agent's prompt. + +```text +Fetch https://blog.localstack.cloud/ai/agents.md and follow the instructions to set up LocalStack on my machine. +``` + +For manual setup of the MCP server and skills, you can follow the steps below. + +## Connect an MCP client + +The LocalStack MCP Server connects MCP-compatible clients to your LocalStack environment. Once configured, your AI assistant can use LocalStack tools to start the container, deploy infrastructure, run AWS CLI commands, inspect logs, manage state, and query resources. + +Start the MCP server with an interactive setup wizard: + +```bash +npx -y @localstack/localstack-mcp-server init +``` + +:::note +The MCP server runs locally and talks to a LocalStack instance. Your AI assistant is the MCP client. For full installation instructions, detailed setup, and the full tool reference, see the [LocalStack MCP Server guide](/aws/tooling/mcp-server/). + +You need a valid [Auth Token](/aws/getting-started/auth-token/) to configure the server. +::: + +## Use agent skills + +[LocalStack Skills](https://github.com/localstack/skills) provide reusable instructions for AI agents working with LocalStack. They help agents follow LocalStack-specific conventions when creating infrastructure, deploying resources, running tests, and inspecting local cloud state. + +Skills are most useful when you want the assistant to follow a repeatable workflow, for example: + +- Scaffold a local AWS application and deploy it to LocalStack. +- Convert an AWS architecture idea into Terraform or CDK that targets LocalStack first. +- Debug a failing local deployment by checking resources, logs, and configuration. +- Save or restore LocalStack state as part of an iterative development loop. + +Refer to the [LocalStack Skills repository](https://github.com/localstack/skills) for available skills and setup instructions. + +## Example prompt sequence + +After LocalStack and your preferred AI tooling are configured, you can use a sequence like this: + +```text +Create a Terraform application with an S3 bucket, a Lambda function, and a DynamoDB table. +Make it deployable to LocalStack with tflocal. +``` + +```text +Deploy the application to LocalStack and fix any errors from the deployment. +``` + +```text +Invoke the Lambda function locally, inspect the DynamoDB table, and summarize what resources were created. +``` + +```text +Add an integration test that verifies the Lambda writes an item to DynamoDB. +Run the test against LocalStack. +``` + +This keeps the feedback loop local while still giving the assistant a realistic AWS-compatible target. + +## Review before applying to AWS + +AI-generated infrastructure still needs review. Treat LocalStack as the first validation step, not as a replacement for code review, tests, or production deployment controls. + +Before applying changes to AWS, check that: + +- The generated infrastructure matches your intended architecture. +- Resource names, IAM policies, and environment variables are appropriate for your project. +- Tests pass against LocalStack. +- You understand any changes the assistant made to application code or deployment configuration. + +## Next steps + +- Configure the [LocalStack MCP Server](/aws/tooling/mcp-server/) if your AI assistant supports MCP. +- Review [LocalStack Skills](https://github.com/localstack/skills) for reusable agent workflows. +- Browse the [LocalStack for AWS services](/aws/services/) reference, or check the [Getting Started FAQ](/aws/getting-started/faq/) for common setup questions. diff --git a/src/content/docs/aws/getting-started/auth-token.mdx b/src/content/docs/aws/getting-started/auth-token.mdx index 8a14e258..0a2326dd 100644 --- a/src/content/docs/aws/getting-started/auth-token.mdx +++ b/src/content/docs/aws/getting-started/auth-token.mdx @@ -1,167 +1,81 @@ --- title: Auth Token -description: Configure your Auth Token to access and activate LocalStack. +description: Configure and manage your LocalStack Auth Token to activate LocalStack and access licensed features. template: doc sidebar: - order: 3 + order: 6 --- -import { Code, Tabs, TabItem } from '@astrojs/starlight/components'; +import { Tabs, TabItem } from '@astrojs/starlight/components'; -## Introduction +## What is an Auth Token? -The Auth Token is required to activate the LocalStack for AWS core cloud emulator. It identifies and authenticates users outside the LocalStack Web Application. -It primarily accesses your workspace and advanced services & features. +An Auth Token is a mandatory credential required to start the LocalStack container and activate licensed features. It links your running LocalStack instance to your workspace license and unlocks the services and capabilities available to your account. -Auth tokens come in two types: a **Developer Auth Token** and a **CI Auth Token**: +You can manage Auth Tokens from the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application. -- The **Developer Auth Token** is linked to a specific user within a specific workspace. - Every user has their own Auth Token. - It cannot be deleted but can be rotated for security reasons if needed. -- The **CI Auth Token** is not associated with any specific user and is designed for use in CI environments and other non-developer contexts. - These tokens are stored in the workspace and can be managed by members with appropriate permissions. - -Both the **Developer Auth Token** and **CI Auth Token** can be managed on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens). - -:::danger - -- It's crucial to keep your Auth Token confidential. - Do not include it in source code management systems, such as Git repositories. -- Be aware that if an Auth Token is committed to a public repository, it is at risk of exposure, and could remain in the repository's history, even if attempts are made to rewrite it. -- In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens). - ::: - -## Managing your License - -To use LocalStack, a license is required. -You can get a license by [signing up for a free LocalStack account](https://www.localstack.cloud/pricing). -Choose between a 14-day trial or explore additional features with our paid offering. -During the trial period, you are welcome to use all the features of LocalStack. - -After initiating your trial or acquiring a license, proceed to assign it to a user by following the steps outlined below: - -- Visit the [Users & Licenses page](https://app.localstack.cloud/workspace/members). -- Select a user in the **Workspace Members** section for license assignment. -- Define user's role via the **Member Role** dropdown. - Single users automatically receive the **Admin** role. -- Toggle **Advanced Permissions** to set specific permissions. - Single users automatically receive full permissions. -- Click **Save** to complete the assignment. - Single users assign licenses to themselves. - -![Assigning a license](/images/aws/assigning-a-license.png) - -If you have joined a workspace, you need to be assigned a license by the workspace administrator. -In case of switching workspaces or licenses, you need to make sure that you are assigned to the correct license. - -:::note -If you do not assign a license, you will not be able to use LocalStack even if you have a valid Auth token. +:::danger[Credential security] +Auth Tokens provide access to your license and workspace. Do not commit tokens to version control. If a token is exposed, rotate it immediately in the LocalStack Web Application. ::: -To view your own assigned license, visit the [My License page](https://app.localstack.cloud/workspace/my-license). -You can further navigate to the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) to view your **Developer Auth Token** and **CI Auth Token**. - -## Configuring your Auth Token +## Token types -LocalStack requires the `LOCALSTACK_AUTH_TOKEN` environment variable to contain your Auth Token. -You can configure your Auth Token in several ways, depending on your use case. -The following sections describe the various methods of setting your Auth Token. +| Token Type | Scope | Use Case | +| :--- | :--- | :--- | +| **Developer Token** | Individual | Local development workstations. Managed per user. | +| **CI Auth Token** | Workspace | Automated pipelines and shared runners. Managed by workspace admins. | -:::danger +## Configure your token -- It's crucial to keep your Auth Token confidential. - Do not include it in source code management systems, such as Git repositories. -- Be aware that if an Auth Token is committed to a public repository, it's at risk of exposure, and could remain in the repository's history, even if attempts are made to rewrite it. -- In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens). - ::: +Authentication requirements vary based on your chosen execution method. -### LocalStack CLI +### lstk -You should set the `LOCALSTACK_AUTH_TOKEN` environment variable either before or during the startup of LocalStack using the `localstack` command-line interface (CLI). +The `lstk` CLI automates the authentication lifecycle. On initial execution, it triggers a browser-based OAuth flow and stores the resulting token in your system keyring. No manual environment variable configuration is required. - - - \nlocalstack start`} - lang="shell" - /> - - - \nlocalstack start`} - lang="powershell" - /> - - - -:::note +```bash +lstk start +``` -1. You can alternatively set the `LOCALSTACK_AUTH_TOKEN` environment variable in your shell session. - This ensures the Auth Token is transmitted to your LocalStack container, enabling key activation. -2. The `localstack auth set-token` command is only available for `localstack` CLI and cannot be used with a Docker/Docker Compose setup. - ::: +### LocalStack CLI -You have the option to run your LocalStack container in the background by appending the `-d` flag to the `localstack start` command. +If you use the LocalStack CLI, set your token with the `auth` command. This stores the token in your local configuration. -The `localstack` CLI automatically detects the Auth Token and appropriately conveys it to the LocalStack container. +```bash +localstack auth set-token +localstack start +``` :::note -If you are using LocalStack with an Auth Token, it's necessary to download the [LocalStack for AWS image](/aws/customization/other-installations/docker-images#localstack-for-aws-image), which includes Pro services and several advanced features. +You can alternatively set the `LOCALSTACK_AUTH_TOKEN` environment variable in your shell session. +The `localstack auth set-token` command is only available for the `localstack` CLI and cannot be used with a Docker or Docker Compose setup. ::: -### Docker +### Docker and Docker Compose -To start LocalStack via Docker, you need to provide the Auth Token using the `-e` flag, which is used for setting environment variables. - -```bash {5} -docker run \ - --rm -it \ - -p 4566:4566 \ - -p 4510-4559:4510-4559 \ - -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:- } \ - localstack/localstack-pro -``` +For direct container execution, inject the token as an environment variable. For complete startup examples, see the [Docker Compose](/aws/getting-started/installation/#docker-compose) and [Docker CLI](/aws/getting-started/installation/#docker-cli) installation options. -For more information about starting LocalStack with Docker, take a look at our [Docker installation](/aws/getting-started/installation/#docker) guide. +**Docker CLI:** -### Docker Compose +```bash +-e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} +``` -To start LocalStack using `docker compose`, you have to include the `LOCALSTACK_AUTH_TOKEN` environment variable in your `docker-compose.yml` file: +**Docker Compose:** ```yaml environment: - - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN- } + - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} ``` -You can manually set the Auth Token, or use the `export` command to establish the Auth Token in your current shell session. -This ensures the Auth Token is transmitted to your LocalStack container, enabling key activation. - -### CI Environments - -CI environments require a CI Auth Token. -Developer Auth Tokens cannot be used in CI. -CI Auth Tokens are available on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) and are configured similarly to Developer Auth Tokens. - -To set the CI Auth Token, add the Auth Token value in the `LOCALSTACK_AUTH_TOKEN` environment variable of your CI provider, and refer to it when starting LocalStack in your CI workflow. -You can find detailed examples in our [LocalStack in CI documentation](/aws/ci-pipelines/). - -## Rotating the Auth Token - -Your personal Auth Token provides full access to your workspace and LocalStack license. -It's important to treat auth tokens as confidential, avoiding sharing or storing them in source control management systems (SCMs) like Git. - -If you believe your Auth Token has been compromised or becomes known to someone else, reset it without delay. -When you reset a token, the old one is immediately deactivated, losing its ability to access your license or workspace. -It is not possible to restore previous tokens. - -To rotate your Auth Token, go to the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and select the **Reset Auth Token** option. +### CI environments -## Licensing configuration & activation checkup +CI environments should use a dedicated CI Auth Token stored in your CI provider's secret manager. +For complete examples, see the [CI/CD guide](/aws/getting-started/ci-cd/). -To avoid logging any licensing-related error messages, set `LOG_LICENSE_ISSUES=0` in your environment. -Refer to our [configuration guide](/aws/customization/configuration-options/#localstack-for-aws) for more information. +## Verify activation -The simplest method to verify if LocalStack is active is by querying the health endpoint for a list of running services: +Verify the activation status by querying the LocalStack info endpoint: @@ -173,61 +87,44 @@ The simplest method to verify if LocalStack is active is by querying the health - ```bash + ```powershell Invoke-WebRequest -Uri http://localhost:4566/_localstack/info | ConvertFrom-Json ``` -The following output would be retrieved: - -```bash +```json title="Output" { - "version": "3.0.0:6dd3f3d", "edition": "pro", - "is_license_activated": true, - "session_id": "7132da5f-a380-44ca-8897-6f0fdfd7b1c9", - "machine_id": "0c49752c", - "system": "linux", - "is_docker": true, - "server_time_utc": "2023-11-21T05:41:33", - "uptime": 161 + "is_license_activated": true } ``` -The `edition` field is always `pro` and the `is_license_activated` field is set to `true`. -Another way to confirm this is by checking the logs of the LocalStack container for a message indicating successful license activation: - -```bash -[...] Successfully activated license -``` - -Otherwise, check our [troubleshooting](#troubleshooting) section. - -## FAQ +The `edition` field should be `pro`, and `is_license_activated` should be `true`. -### How do I activate older versions of LocalStack (Before v3.0)? +## License assignment -Prior to the introduction of Auth Tokens, LocalStack used **API keys** managed through the `LOCALSTACK_API_KEY` environment variable for activation. +An Auth Token can only activate licensed features if a license is assigned to the associated user or workspace. -For backwards compatibility, we've updated our back-end to accept new Auth Tokens within the `LOCALSTACK_API_KEY` variable. -You can use the new Auth Token in the same way you previously used the API key. +1. Navigate to the [Users & Licenses page](https://app.localstack.cloud/workspace/members). +2. Identify the target user in **Workspace Members**. +3. Select the appropriate **Member Role**. +4. Save the configuration to activate the license for that identity. -### When will the legacy API keys be phased out? +:::note +LocalStack cannot activate licensed features unless the token belongs to a user or workspace with an assigned license. +::: -In early 2025, we will begin phasing out legacy API keys entirely. -After the sunsetting period, legacy API and legacy CI keys will no longer activate or work with LocalStack. +## Rotate a token -During the sunsetting period, the legacy service will experience scheduled downtimes. -These are planned to encourage users to transition to new Auth Tokens while minimizing impact for those who have not yet updated. +Rotate an Auth Token if it has been exposed, shared accidentally, or stored in a place where it should not be. Go to the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) and select the reset option for the affected token. -The downtime schedule will be communicated well in advance, allowing users ample time to switch to the new Auth Tokens. +After rotation, update every local shell, container configuration, or CI secret that used the old token. ## Troubleshooting -While using Auth Tokens, LocalStack demands a successful license activation for startup. -If the activation of the license is unsuccessful, LocalStack will exit and display error messages. +LocalStack requires successful license activation during startup. If activation fails, LocalStack exits and displays an error message: ```bash =============================================== @@ -242,11 +139,11 @@ Due to this error, Localstack has quit. LocalStack for AWS features can only be - If you want to continue using LocalStack without pro features you can set `ACTIVATE_PRO=0`. ``` -The key activation in LocalStack may fail for several reasons, and the most common ones are listed below in this section. +Activation may fail for several reasons, and the most common ones are listed below. -### Missing Credentials +### Missing credentials -You need to provide either an Auth Token to start the LocalStack for AWS image successfully. +You need to provide an Auth Token to start the LocalStack for AWS image successfully. You can find your Auth Token on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application. If you are using the `localstack` CLI, you can set the `LOCALSTACK_AUTH_TOKEN` environment variable to your Auth Token or use the following command to set it up: @@ -255,12 +152,12 @@ If you are using the `localstack` CLI, you can set the `LOCALSTACK_AUTH_TOKEN` e localstack auth set-token ``` -### Invalid License +### Invalid license The issue may occur if there is no valid license linked to your account due to expiration or if the license has not been assigned. You can check your license status in the LocalStack Web Application on the [My License page](https://app.localstack.cloud/workspace/my-license). -### License Server Unreachable +### License server unreachable LocalStack initiates offline activation when the license server is unreachable, requiring re-activation every 24 hours. Log output may indicate issues with your machine resolving the LocalStack API domain, which can be verified using a tool like `dig`: @@ -273,4 +170,8 @@ If the result shows a status other than `status: NOERROR`, your machine is unabl Certain corporate DNS servers may filter requests to specific domains. Kindly reach out to your network administrator to safelist `localstack.cloud` domain. -If you have any further problems concerning your license activation, or if the steps do not help, do not hesitate to [contact us](https://localstack.cloud/contact/). +If you have any further problems concerning your license activation, or if the steps do not help, don't hesitate to [contact us](https://localstack.cloud/contact/). + +## Next steps + +After configuring your Auth Token, continue to the [Local Development guide](/aws/getting-started/local-development/) to start LocalStack and deploy a local serverless API. diff --git a/src/content/docs/aws/getting-started/ci-cd.mdx b/src/content/docs/aws/getting-started/ci-cd.mdx new file mode 100644 index 00000000..b3dacb0e --- /dev/null +++ b/src/content/docs/aws/getting-started/ci-cd.mdx @@ -0,0 +1,211 @@ +--- +title: CI Integration +description: Use LocalStack in CI pipelines to run integration tests against local AWS infrastructure. +template: doc +sidebar: + order: 4 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +## Introduction + +LocalStack helps you run integration tests in CI against emulated AWS infrastructure. Your pipeline starts LocalStack inside the CI job, deploys or prepares the resources your application needs, runs tests against the local endpoint, and then discards the environment when the job ends. + +## How LocalStack works in CI + +A typical CI job with LocalStack follows this flow: + +1. Check out your application code. +2. Start LocalStack in the CI runner. +3. Configure a CI Auth Token through the CI provider's secret manager. +4. Deploy test infrastructure with tools such as `awslocal`, `tflocal`, `cdklocal`, or your application's test harness. +5. Run integration tests against the LocalStack endpoint. +6. Collect logs, test reports, and artifacts from the job. + +This gives every pipeline run a fresh AWS-compatible environment without creating cloud resources in an AWS account. + +## What changes from local development + +CI runs are usually more constrained than local development: + +- Use a dedicated **CI Auth Token** instead of a personal Developer Token. +- Store `LOCALSTACK_AUTH_TOKEN` as a protected CI secret. +- Start LocalStack non-interactively as part of the job. +- Treat the LocalStack container as ephemeral unless your workflow explicitly saves state. +- Export logs and test reports before the runner shuts down. + +Docker and Docker Compose are still common ways to run containers inside CI runners, but they are not CI tools by themselves. For container startup details, see the [Installation guide](/aws/getting-started/installation/#container-and-orchestration-tools). For provider-specific CI setup, use the integration guides below. + +## Choose your CI provider + +Start with the CI system you use. These snippets show the basic LocalStack startup shape for each provider; the linked guides include authentication, configuration, logs, state management, and provider-specific caveats. + +:::note +For brevity, these snippets show only the LocalStack startup shape. Apart from the GitHub Actions example, they assume your CI Auth Token is already exposed to the job as the `LOCALSTACK_AUTH_TOKEN` environment variable. Store it as a secret in your CI provider before running them, and see [Authentication in CI](#authentication-in-ci) below. +::: + + + + + ```yaml + - name: Start LocalStack + uses: LocalStack/setup-localstack@main + with: + image-tag: 'latest' + install-awslocal: 'true' + env: + LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} + ``` + + See the [GitHub Actions guide](/aws/integrations/continuous-integration/github-actions/) for the full setup. + + + + + ```yaml + version: '2.1' + orbs: + python: circleci/python@4.0.0 + jobs: + localstack-test: + machine: + image: ubuntu-2204:current + steps: + - checkout + - run: + name: Install lstk and awslocal + command: | + python3 -m pip install --user --upgrade pip + python3 -m pip install --user localstack awscli-local[ver1] + echo 'export PATH=$HOME/.local/bin:$PATH' >> "$BASH_ENV" + - run: + name: Start LocalStack + command: | + source "$BASH_ENV" + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 + ``` + + See the [CircleCI guide](/aws/integrations/continuous-integration/circleci/) for the full setup. + + + + + ```yaml + image: python:3.9 + + definitions: + services: + docker: + memory: 2048 + + pipelines: + default: + - step: + name: Test LocalStack + services: + - docker + script: + - export DOCKER_SOCK=$DOCKER_HOST + - export AWS_ENDPOINT_URL="http://localhost.localstack.cloud:4566" + - echo "${BITBUCKET_DOCKER_HOST_INTERNAL} localhost.localstack.cloud " >> /etc/hosts + - pip install localstack awscli-local + - docker run -d --rm -p 4566:4566 -p 4510-4559:4510-4559 -e DOCKER_SOCK=tcp://${BITBUCKET_DOCKER_HOST_INTERNAL}:2375 -e DOCKER_HOST=tcp://${BITBUCKET_DOCKER_HOST_INTERNAL}:2375 --name localstack-main localstack/localstack + - localstack wait -t 60 + ``` + + See the [Bitbucket Pipelines guide](/aws/integrations/continuous-integration/bitbucket/) for the full setup. + + + + + ```yaml + version: 0.2 + + phases: + pre_build: + commands: + - pip3 install localstack awscli + - docker pull public.ecr.aws/localstack/localstack:latest + - localstack start -d + - localstack wait -t 30 + ``` + + See the [CodeBuild guide](/aws/integrations/continuous-integration/codebuild/) for the full setup. + + + + + ```yaml + stages: + - test + + variables: + DOCKER_HOST: tcp://docker:2375 + DOCKER_TLS_CERTDIR: "" + LOCALSTACK_HOST: "localstack:4566" + + services: + - name: localstack/localstack:latest + alias: localstack + - name: docker:dind + alias: docker + command: ["--tls=false"] + + localstack-test: + stage: test + image: python:3.11 + script: + - pip install awscli-local + - awslocal s3 mb s3://test-bucket + ``` + + See the [GitLab CI guide](/aws/integrations/continuous-integration/gitlab-ci/) for the full setup. + + + + + ```yaml + language: python + + services: + - docker + + python: + - "3.8" + + before_install: + - python -m pip install localstack awscli-local[ver1] + - docker pull localstack/localstack + - localstack start -d + - localstack wait -t 30 + ``` + + See the [Travis CI guide](/aws/integrations/continuous-integration/travis-ci/) for the full setup. + + + + +You can also start from the [CI integrations overview](/aws/integrations/continuous-integration/) if you want a broader explanation of the CI workflow. + +## Authentication in CI + +CI environments should use a CI Auth Token. Create one from the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens), then store it as `LOCALSTACK_AUTH_TOKEN` in your CI provider's secret manager. + +Do not commit tokens to your repository or write them directly into workflow files. For more details on token types and rotation, see the [Auth Token guide](/aws/getting-started/auth-token/). + +## State in CI + +Most CI jobs should start with a clean LocalStack instance. A fresh instance makes test runs reproducible and avoids hidden dependencies between jobs. + +If your pipeline needs state across jobs or workflow stages, use one of the state management options documented outside this getting started page: + +- [Cloud Pods](/aws/capabilities/state-management/cloud-pods/) to save and restore named LocalStack state snapshots. +- [State export and import](/aws/capabilities/state-management/export-import-state/) to move state through artifacts or caches. +- [Persistence](/aws/capabilities/state-management/persistence/) when the same runner keeps a mounted LocalStack volume. + +## Next steps + +After choosing your CI provider, continue to [AI & Agent Workflows](/aws/getting-started/ai-workflows/) to learn how AI coding assistants can help generate, deploy, and test LocalStack-backed AWS applications. diff --git a/src/content/docs/aws/getting-started/faq.mdx b/src/content/docs/aws/getting-started/faq.mdx index 62106f67..3bf0cbd7 100644 --- a/src/content/docs/aws/getting-started/faq.mdx +++ b/src/content/docs/aws/getting-started/faq.mdx @@ -3,7 +3,7 @@ title: FAQ description: Frequently asked questions about LocalStack for AWS. template: doc sidebar: - order: 5 + order: 7 --- import { Tabs, TabItem } from '@astrojs/starlight/components'; @@ -35,20 +35,6 @@ To resolve the issue follow the steps: For other SSL-related issues encountered during startup โ€” such as Python `CERTIFICATE_VERIFY_FAILED` tracebacks or corporate TLS interception โ€” see [How do I diagnose if my SSL traffic is being intercepted by a corporate proxy?](#how-do-i-diagnose-if-my-ssl-traffic-is-being-intercepted-by-a-corporate-proxy). -### How to update my LocalStack CLI? - -If the LocalStack CLI version is heavily outdated, it might lead to issues with container startup and debug commands. -If you are using an older version of LocalStack, you can update it by running the following command: - -```bash -pip install --upgrade localstack localstack-ext -``` - -If you are running a newer version of LocalStack, you can check the version by running the following command: - -```bash -localstack update localstack-cli -``` ### Is using `localhost.localstack.cloud:4566` to set as the endpoint for AWS services recommended? @@ -122,23 +108,6 @@ aws ssm put-parameter --name "//test/parameter/new" --type String --value "test" For additional known issues related to Git Bash, you can refer to the following link: [Git Bash Known Issues](https://github.com/git-for-windows/build-extra/blob/main/ReleaseNotes.md#known-issues) -### How to fix LocalStack CLI (Python) UTF-8 encoding issue under Windows? - -If you are using LocalStack CLI under Windows, you might run into encoding issues. -To fix this, set the following environment variables: -Set the system locale (language for non-Unicode programs) to UTF-8 to avoid Unicode errors. - -Follow these steps: - -- Open the Control Panel. -- Go to "Clock and Region" or "Region and Language." -- Click on the "Administrative" tab. -- Click on the "Change system locale" button. -- Select "Beta: Use Unicode UTF-8 for worldwide language support" and click "OK." -- Restart your computer to apply the changes. - -If you would like to keep the system locale as it is, you can mitigate the issue by using the command `localstack --no-banner`. - ### How do I resolve connection issues with proxy blocking access to LocalStack's BigData image? A company proxy can lead to connection issues. @@ -626,14 +595,6 @@ If that happens, see [How do I trust my corporate TLS interceptor certificate in Offline images for airgapped environments are available on our enterprise tier, please reach out to our sales team. -### Why does LocalStack startup fail with "Docker not available"? - -The LocalStack CLI cannot reach the Docker daemon. Common fixes: - -- Start Docker Desktop and confirm it's running. -- Verify `docker ps` works as your current user (no `sudo`). -- On macOS, check that `/var/run/docker.sock` is reachable from Docker Desktop. -- If you use Colima, Rancher, or Podman, make sure the `DOCKER_HOST` environment variable points at the correct socket. ### Why does LocalStack fail with "ports are not available: exposing port TCP 127.0.0.1:443"? diff --git a/src/content/docs/aws/getting-started/index.md b/src/content/docs/aws/getting-started/index.md deleted file mode 100644 index e6bb3355..00000000 --- a/src/content/docs/aws/getting-started/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Overview -description: This section describes how to get started with LocalStack using a variety of options, and provides details on how LocalStack can be configured to fit the needs of a local cloud sandbox for development, testing, and experimentation. -template: doc -editUrl: false -sidebar: - order: 1 ---- - -[LocalStack](https://localstack.cloud) is a cloud service emulator that runs in a single container on your laptop or in your CI environment. -With LocalStack, you can run your AWS applications or Lambdas entirely on your local machine without connecting to a remote cloud provider! - -Whether you are testing complex CDK applications or Terraform configurations, or just beginning to learn about AWS services, LocalStack helps speed up and simplify your testing and development workflow. - -LocalStack supports a growing number of [AWS services](/aws/services/) -, like [Lambda](/aws/services/lambda), [S3](/aws/services/s3), [DynamoDB](/aws/services/dynamodb), [Kinesis](/aws/services/kinesis), [SQS](/aws/services/sqs), [SNS](/aws/services/sns), and more! -[LocalStack for AWS](https://localstack.cloud/pricing) also supports APIs and advanced features to make your cloud development experience a breeze. - -You can find a comprehensive list of supported APIs on each AWS service page. - -LocalStack also provides additional features to make your life as a cloud developer easier! - -Check out LocalStack's [Cloud Developer Tools](/aws/developer-tools/). diff --git a/src/content/docs/aws/getting-started/index.mdx b/src/content/docs/aws/getting-started/index.mdx new file mode 100644 index 00000000..24414b24 --- /dev/null +++ b/src/content/docs/aws/getting-started/index.mdx @@ -0,0 +1,68 @@ +--- +title: Overview +description: Introduction to LocalStack for AWS, covering core use cases, local cloud capabilities, and deployment options for development and testing. +template: doc +editUrl: false +sidebar: + order: 1 +--- + +import { SectionCards } from '../../../../components/SectionCards.tsx'; + +LocalStack provides a cloud service emulator that runs within a single container on your local machine or CI environment. It delivers a functional AWS environment including Lambda, DynamoDB, S3, SQS, and [80+ supported services](/aws/services/), enabling development and testing without an AWS account or cloud-related costs. + +### Core Use Cases + +- **Accelerate development loops**: Test changes against local AWS services instantly to bypass deployment wait times. +- **Automate integration testing**: Execute integration tests against local AWS infrastructure within pull requests to identify regressions before production. +- **Validate IaC**: Deploy Terraform, CDK, or CloudFormation templates to LocalStack to verify infrastructure logic before applying changes to a cloud environment. +- **Experimental sandbox**: Explore new AWS services and architectures in a risk-free environment. + +LocalStack also provides advanced features for team collaboration and security, including [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods/) for state management, [IAM policy enforcement](/aws/developer-tools/security-testing/iam-policy-enforcement/), and [Chaos Engineering](/aws/developer-tools/chaos-engineering/). + +## Start with the basics + + + +:::note +**Enterprise Kubernetes Deployment:** LocalStack also supports execution within Kubernetes clusters via the Operator or Helm charts. This model enables dynamic scaling, environment isolation, and native orchestration. See our [Kubernetes Deployment guide](/aws/customization/kubernetes/) for more information. +::: diff --git a/src/content/docs/aws/getting-started/installation.mdx b/src/content/docs/aws/getting-started/installation.mdx index c5e333e0..3aceb90b 100644 --- a/src/content/docs/aws/getting-started/installation.mdx +++ b/src/content/docs/aws/getting-started/installation.mdx @@ -1,6 +1,6 @@ --- title: Installation -description: Basic installation guide to get started with LocalStack on your local machine. +description: Install LocalStack with lstk, Docker, Docker Compose, or Helm. template: doc sidebar: order: 2 @@ -9,296 +9,74 @@ sidebar: import { Code, LinkButton, Tabs, TabItem } from '@astrojs/starlight/components'; import { LOCALSTACK_AWS_VERSION } from 'astro:env/server'; -## LocalStack CLI +## Introduction -The quickest way get started with LocalStack is by using the LocalStack CLI. -It allows you to start LocalStack from your command line. -Please make sure that you have a working [Docker installation](https://docs.docker.com/get-docker/) on your machine before moving on. +LocalStack provides multiple installation paths depending on your development environment and requirements. We recommend a CLI-based installation for the most consistent local startup experience. -### Installing LocalStack CLI +Use [`lstk`](#lstk) to install, authenticate, and start LocalStack with minimal setup. -The CLI starts and manages the LocalStack Docker container. -For alternative methods of managing the LocalStack container, see our [alternative installation instructions](#alternatives). +LocalStack for AWS features require an [Auth Token](/aws/getting-started/auth-token/) to activate your running instance. `lstk` handles authentication through a browser-based login flow, while Docker and CI workflows can use `LOCALSTACK_AUTH_TOKEN`. - - - - -You can download the pre-built binary for your architecture using the link below: - - - x86-64 - - - ARM64 - - -or use the curl commands below: - -For x86-64: - - - -For ARM64: - - - -Then extract the LocalStack CLI from the terminal: - - - -
-Alternative: Homebrew on Linux - -If you are using [Homebrew for Linux](https://docs.brew.sh/Homebrew-on-Linux), you can install the LocalStack CLI directly from our official LocalStack tap: - -```bash -brew install localstack/tap/localstack-cli -``` - -
- - - - - -You can install the LocalStack CLI using Brew directly from our official LocalStack tap: - -```bash -brew install localstack/tap/localstack-cli -``` - -
-Alternative: Binary Download - -You may download the binary for your architecture using the link below: - - - Intel (AMD64) - - -or use the following curl command: - - - -Then extract the LocalStack CLI from the terminal: - - +## lstk -
- - - - -You can download the pre-built binary for your architecture using the link below: - - - Intel (AMD64) - - -Then extract the archive and execute the binary in Powershell. - - - - +`lstk` is a lightweight CLI for LocalStack that manages the authentication and container lifecycle in a single workflow. -If you cannot use the binary releases of LocalStack, you can install the Python distribution. +**Requirement:** You must have a working [Docker installation](https://docs.docker.com/get-docker/) before proceeding. -Please make sure to install the following before moving ahead: -- [Python](https://docs.python.org/3/using/index.html) -- [pip](https://pip.pypa.io/en/stable/installation/) +### Install lstk -Next install the LocalStack CLI in your Python environment by running: - -```bash -python3 -m pip install --upgrade localstack -``` - -:::note -To download a specific version of LocalStack, replace `` with the required version from [changelog page](/aws/changelog). - -```bash -python3 -m pip install localstack== -``` - -::: - -:::tip[MacOS Sierra?] -If you have problems with permissions in MacOS X Sierra, install with: - -```bash -python3 -m pip install --user localstack -``` - -::: - -:::danger -Do not use `sudo` or the `root` user when starting LocalStack. -It should be installed and started entirely under a local non-root user. -::: - - + + + ```bash + brew install localstack/tap/lstk + ``` + + + ```bash + npm install -g @localstack/lstk + ``` + + + Download the binary for your platform from the [GitHub Releases](https://github.com/localstack/lstk/releases) and add it to your `PATH`. + -### Starting LocalStack - -To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal: - - - -You are all set! - -:::note -To start LocalStack, you must first [set up your auth token](/aws/getting-started/auth-token). -::: - -Once you've set up your auth token, you can start LocalStack with the following command: +### Start lstk ```bash -localstack start # start localstack in background with -d flag +lstk start ``` -{/* prettier-ignore */} - - -### Updating LocalStack CLI - -The LocalStack CLI allows you to easily update the different components of LocalStack. -To check the various options available for updating, run: +The first execution initiates a browser-based login flow. Subsequent starts use credentials stored in your system keyring. -```bash -localstack update --help -``` +### Update lstk ```bash -Usage: localstack update [OPTIONS] COMMAND [ARGS]... - - Update different LocalStack components. - -Options: - -h, --help Show this message and exit. - -Commands: - all Update all LocalStack components - docker-images Update docker images LocalStack depends on - localstack-cli Update LocalStack CLI +lstk update ``` -:::note -Updating the LocalStack CLI using `localstack update localstack-cli` and `localstack update all` will work only if it was installed from the Python distribution. -If it was installed using the pre-built binary or via Brew, please run the installation steps again to update to the latest version. -::: - -## Alternatives - -Besides using the CLI, there are other ways of starting and managing your LocalStack instance: - -- [LocalStack Desktop](#localstack-desktop)\ - Get a desktop experience and work with your local LocalStack instance via the UI. - -- [LocalStack Docker Extension](#localstack-docker-extension)\ - Use the LocalStack extension for Docker Desktop to work with your LocalStack instance. +For more details, see the [lstk documentation](/aws/developer-tools/running-localstack/lstk/). -- [Docker-Compose](#docker-compose)\ - Use Docker Compose to configure and start your LocalStack Docker container. +## Container and orchestration tools -- [Docker](#docker)\ - Use the Docker CLI to manually start the LocalStack Docker container. +Use these methods when you need explicit container configuration, want to run LocalStack alongside other services, or deploy LocalStack in CI and Kubernetes environments. +For everyday local development, `lstk` is usually simpler. -- [LocalStack Operator](#localstack-operator)\ - Use the LocalStack Operator to deploy and manage LocalStack instances inside a Kubernetes cluster. +### Docker Compose -LocalStack runs inside a Docker container, and the above options are different ways to start and manage the LocalStack Docker container. +Use Docker Compose when you want a reusable configuration file that can be shared across a team or checked into a project repository. +Create a `docker-compose.yml` with the following configuration: -The LocalStack emulator is available on Docker Hub (`localstack/localstack-pro`). - -For a comprehensive overview of the LocalStack images, check out our [Docker images documentation](/aws/customization/other-installations/docker-images). - -### LocalStack Desktop - -Learn more about our desktop client at [LocalStack Desktop](/aws/developer-tools/running-localstack/localstack-desktop) and download it [here](https://app.localstack.cloud/download). - -### LocalStack Docker Extension - -Install our [official Docker Desktop extension](https://hub.docker.com/extensions/localstack/localstack-docker-desktop) to manage LocalStack. -See [LocalStack Docker Extension](/aws/customization/other-installations/localstack-docker-extension) for more information. - -### Docker-Compose - -To use LocalStack without the [LocalStack CLI](#localstack-cli), you have the option of running the LocalStack Docker container by yourself. -If you want to manually manage your Docker container, it's usually a good idea to use [Docker Compose](https://docs.docker.com/compose/reference/) in order to simplify your container configuration. - -#### Prerequisites - -- [Docker](https://docs.docker.com/get-docker/) -- [Docker Compose](https://docs.docker.com/compose/install/) (version 1.9.0+) - -#### Starting LocalStack with Docker-Compose - -You can start LocalStack with [Docker Compose](https://docs.docker.com/compose/) by configuring a `docker-compose.yml` file. -Docker Compose v1.9.0 and above is supported. - -```yaml showshowLineNumbers +```yaml showLineNumbers services: localstack: container_name: '${LOCALSTACK_DOCKER_NAME:-localstack-main}' - image: localstack/localstack-pro # required for Pro + image: localstack/localstack ports: - '127.0.0.1:4566:4566' # LocalStack Gateway - '127.0.0.1:4510-4559:4510-4559' # external services port range - - '127.0.0.1:443:443' # LocalStack HTTPS Gateway (Pro) + - '127.0.0.1:443:443' # LocalStack HTTPS Gateway environment: # Activate LocalStack for AWS: https://docs.localstack.cloud/getting-started/auth-token/ - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} # required for Pro @@ -310,55 +88,11 @@ services: - '/var/run/docker.sock:/var/run/docker.sock' ``` -Start the container by running the following command: +Execute `docker compose up` to start. -```bash -docker compose up -``` +### Docker CLI -:::note - -- This command pulls the current nightly build from the `main` branch (if you don't have the image locally) and **not** the latest supported version. - If you want to use a specific version, set the appropriate LocalStack image tag at `services.localstack.image` in the `docker-compose.yml` file (for example `localstack/localstack:`). - -- If you are using LocalStack with an [Auth Token](/aws/getting-started/auth-token), you need to specify the image tag as `localstack/localstack-pro` in the `docker-compose.yml` file. - Going forward, `localstack/localstack-pro` image will contain our Pro-supported services and APIs. - -- This command reuses the image if it's already on your machine, i.e. it will **not** pull the latest image automatically from Docker Hub. - -- Mounting the Docker socket `/var/run/docker.sock` as a volume is required for some services that use Docker to provide the emulation, such as AWS Lambda. - Check out the [Lambda providers](/aws/services/lambda) documentation for more information. - -- To facilitate interoperability, configuration variables can be prefixed with `LOCALSTACK_` in docker. - For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`. - -- If using the Docker default bridge network using `network_mode: bridge`, container name resolution will not work inside your containers. - Please consider removing it, if this functionality is needed. - -- To configure an Auth Token, refer to the [Auth Token](/aws/getting-started/auth-token) documentation. - ::: - -Please note that there are a few pitfalls when configuring your stack manually via docker-compose (e.g., required container name, Docker network, volume mounts, and environment variables). -We recommend using the LocalStack CLI to validate your configuration, which will print warning messages in case it detects any potential misconfigurations: - -```bash -localstack config validate -``` - -### Docker - -You can also directly start the LocalStack container using the Docker CLI instead of [Docker-Compose](#docker-compose). -This method requires more manual steps and configuration, but it gives you more control over the container settings. - -#### Prerequisites - -Please make sure that you have a working [Docker installation](https://docs.docker.com/get-docker/) on your machine before moving on. -You can check if Docker is correctly configured on your machine by executing `docker info` in your terminal. -If it does not report an error (but shows information on your Docker system), you're good to go. - -#### Starting LocalStack with Docker - -You can start the Docker container simply by executing the following `docker run` command: +Use the Docker CLI for one-off starts or when you want to test a container configuration before moving it into Compose: ```bash docker run \ @@ -368,50 +102,39 @@ docker run \ -p 127.0.0.1:443:443 \ -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ -v /var/run/docker.sock:/var/run/docker.sock \ - localstack/localstack-pro + localstack/localstack ``` :::note +The Docker Compose and Docker CLI examples above use the same runtime settings: -- This command pulls the current nightly build from the `main` branch (if you don't have the image locally) and **not** the latest supported version. - If you want to use a specific version of LocalStack, use the appropriate tag: `docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack:`. - Check-out the [changelog page](/aws/changelog) to know more about specific LocalStack versions. - -- If you are using LocalStack with an [Auth Token](/aws/getting-started/auth-token), you need to specify the image tag as `localstack/localstack-pro` in your Docker setup. - Going forward, `localstack/localstack-pro` image will contain our Pro-supported services and APIs. +- The `4566` port exposes the LocalStack Gateway. +- The `4510-4559` range exposes external service ports used by services that bind additional endpoints. +- The `443` port exposes the LocalStack HTTPS Gateway. +- The Docker socket mount is required for services that start additional containers, such as Lambda. +- Docker reuses a local image if one already exists. Pull explicitly or pin an image tag, such as `localstack/localstack:`, when you need reproducible CI or team environments. +- If you use Docker bridge networking, container name resolution may not work as expected from other containers. Prefer the default LocalStack networking setup unless you have a specific reason to customize it. +- Configuration variables can be prefixed with `LOCALSTACK_` in Docker. For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`. -- This command reuses the image if it's already on your machine, i.e. it will **not** pull the latest image automatically from Docker Hub. - -- Mounting the Docker socket `/var/run/docker.sock` as a volume is required for some services that use Docker to provide the emulation, such as AWS Lambda. - Check out the [Lambda providers](/aws/services/lambda) documentation for more information. - -- When using Docker to manually start LocalStack, you will have to configure the container on your own (see [docker-compose-pro.yml](https://github.com/localstack/localstack/blob/main/docker-compose-pro.yml) and [Configuration](/aws/customization/configuration-options). - This could be seen as the "expert mode" of starting LocalStack. - If you are looking for a simpler method of starting LocalStack, please use the [LocalStack CLI](#localstack-cli). +For more details, see the [Docker images](/aws/customization/other-installations/docker-images/), [configuration](/aws/customization/configuration-options/), and [networking](/aws/customization/networking/) documentation. +::: -- To facilitate interoperability, configuration variables can be prefixed with `LOCALSTACK_` in docker. - For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`. +### Helm (Kubernetes) -- To configure an Auth Token, refer to the [Auth Token](/aws/getting-started/auth-token) documentation. - ::: +Deploy LocalStack to a Kubernetes cluster: -### LocalStack Operator +```bash +helm repo add localstack-repo https://helm.localstack.cloud +helm upgrade --install localstack localstack-repo/localstack +``` -If you want to deploy LocalStack in your [Kubernetes](https://kubernetes.io) cluster, you can use the [LocalStack Operator](/aws/customization/kubernetes/kubernetes-operator). +## Graphical user interfaces (GUIs) -## What's next? +### LocalStack Desktop -Now that you have LocalStack up and running, the following resources might be useful for your next steps: +Manage local instances via a standalone desktop application. [Download here](https://app.localstack.cloud/download). -- Check out our [Quickstart guide](/aws/getting-started/quickstart) if you are a new user to get started with LocalStack quickly. -- [Use the LocalStack integrations](/aws/customization/integrations) to interact with LocalStack and other integrated tools, for example: - - Use `awslocal` to use the AWS CLI against your local cloud! - - Use the Serverless Framework with LocalStack! - - And many more! -- [Find out how to configure LocalStack](/aws/customization/configuration-options) such that it perfectly fits your need. -- [Use LocalStack in your CI environment](/aws/ci-pipelines/) to increase your code quality. -- [Checkout LocalStack's Cloud Developer Tools](/aws/developer-tools/) to further increase your development efficiency with LocalStack. -- Find out about the ways you can [configure LocalStack](/aws/customization/configuration-options). +Install the [official extension](https://hub.docker.com/extensions/localstack/localstack-docker-desktop) to manage LocalStack directly from the Docker Desktop. ## Troubleshooting @@ -446,9 +169,13 @@ DNS_ADDRESS=0 localstack start You can now avail logging output and error reporting using LocalStack logs. To access the logs, run the following command: + + ```bash -localstack logs +lstk logs ``` + + AWS requests are now logged uniformly in the INFO log level (set by default or when `DEBUG=0`). The format is: @@ -483,3 +210,7 @@ After running the task, run the diagnostic endpoint and share the archive file w We have extensive network troubleshooting documentation available [here](/aws/customization/networking/). If this does not solve your problem then please [reach out to LocalStack Support](/aws/help-support/get-help/). + +## Next steps + +Now that you've completed installation, proceed to the [Auth Token guide](/aws/getting-started/auth-token/) to activate LocalStack and prepare your environment for local development. diff --git a/src/content/docs/aws/getting-started/local-development.mdx b/src/content/docs/aws/getting-started/local-development.mdx new file mode 100644 index 00000000..dd0920c7 --- /dev/null +++ b/src/content/docs/aws/getting-started/local-development.mdx @@ -0,0 +1,285 @@ +--- +title: Local Development +description: Deploy an AWS serverless API locally using Lambda and DynamoDB on LocalStack. +template: doc +sidebar: + order: 3 +--- + +import { Code, Tabs, TabItem, Steps } from '@astrojs/starlight/components'; +import { LOCALSTACK_AWS_VERSION } from 'astro:env/server'; + +## Introduction + +This guide walks you through starting LocalStack and deploying a serverless API consisting of a Lambda function and a DynamoDB table. You will perform the entire deployment on your local machine without an AWS account. + +A successful deployment results in a: + +- **Serverless API:** A Lambda function with a configured function URL. +- **Persistence Layer:** A DynamoDB table for message storage. +- **Local Cloud Environment:** A fully functional local sandbox that emulates AWS services. + +Choose your preferred deployment method: **Terraform** or **AWS CLI**. + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) engine installed and running. +- A [LocalStack account](https://app.localstack.cloud/sign-up) and a valid [LocalStack Auth Token](/aws/getting-started/auth-token/). +- Either [Terraform CLI](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) or [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed, depending on your preferred deployment method. + +If you haven't installed LocalStack yet, follow the [installation guide](/aws/getting-started/installation/) to get started. + +## Step 1: Install and start LocalStack + +Start LocalStack: + +```bash +lstk start +``` + +The first run triggers a browser-based authentication flow. After authentication, the CLI pulls the LocalStack image and initializes the container. + +When the container is ready, you will see the following logs: + +```text +โœ”๏ธŽ LocalStack ready (containerId: 400b3e61f3c6) +โ€ข Endpoint: localhost.localstack.cloud:4566 +โ€ข Web app: https://app.localstack.cloud +``` + +## Step 2: Deploy the serverless API + +You can deploy the Lambda function and DynamoDB table using either our AWS CLI wrapper `lstk aws` or our Terraform wrapper `tflocal`. +These tools automatically route AWS API calls to your LocalStack container, so you do not need AWS account credentials for this guide. + + + + + + 1. Create the Lambda function source. Execute the following to create a project directory, a function file and a Python handler: + + ```bash + mkdir -p /tmp/localstack-demo + cat > /tmp/localstack-demo/handler.py << 'EOF' + import json, boto3, os, uuid + + def handler(event, context): + table = boto3.resource('dynamodb').Table(os.environ['TABLE_NAME']) + method = event.get('requestContext', {}).get('http', {}).get('method', 'GET') + # Function URL POST, or direct invoke (e.g. Resource Browser) with a message + if method == 'POST' or 'message' in event: + data = json.loads(event.get('body', '{}')) if method == 'POST' else event + item = {'id': str(uuid.uuid4()), **data} + table.put_item(Item=item) + return {'statusCode': 200, 'body': json.dumps(item)} + result = table.scan() + return {'statusCode': 200, 'body': json.dumps(result['Items'])} + EOF + cd /tmp/localstack-demo && zip handler.zip handler.py + ``` + + 2. Create the DynamoDB table: + + ```bash + lstk aws dynamodb create-table \ + --table-name Messages \ + --attribute-definitions AttributeName=id,AttributeType=S \ + --key-schema AttributeName=id,KeyType=HASH \ + --billing-mode PAY_PER_REQUEST + ``` + + 3. Deploy the Lambda function: + + ```bash + lstk aws lambda create-function \ + --function-name messages-api \ + --runtime python3.12 \ + --handler handler.handler \ + --zip-file fileb:///tmp/localstack-demo/handler.zip \ + --role arn:aws:iam::000000000000:role/lambda-role \ + --environment Variables={TABLE_NAME=Messages} + + lstk aws lambda wait function-active --function-name messages-api + ``` + + 4. Configure a function URL and retrieve the endpoint: + + ```bash + lstk aws lambda create-function-url-config \ + --function-name messages-api \ + --auth-type NONE + + LAMBDA_URL=$(lstk aws lambda list-function-url-configs \ + --function-name messages-api \ + --query 'FunctionUrlConfigs[0].FunctionUrl' \ + --output text) + echo $LAMBDA_URL + ``` + + + + + + + + 1. Create a project directory and a `main.tf` file: + + ```bash + mkdir -p /tmp/localstack-demo + cat > /tmp/localstack-demo/main.tf << 'TF' + terraform { + required_providers { + aws = { source = "hashicorp/aws" } + archive = { source = "hashicorp/archive" } + } + } + + resource "aws_dynamodb_table" "messages" { + name = "Messages" + billing_mode = "PAY_PER_REQUEST" + hash_key = "id" + attribute { + name = "id" + type = "S" + } + } + + data "archive_file" "lambda" { + type = "zip" + output_path = "${path.module}/handler.zip" + source { + filename = "handler.py" + content = <<-EOF + import json, boto3, os, uuid + def handler(event, context): + table = boto3.resource('dynamodb').Table(os.environ['TABLE_NAME']) + method = event.get('requestContext', {}).get('http', {}).get('method', 'GET') + # Function URL POST, or direct invoke (e.g. Resource Browser) with a message + if method == 'POST' or 'message' in event: + data = json.loads(event.get('body', '{}')) if method == 'POST' else event + item = {'id': str(uuid.uuid4()), **data} + table.put_item(Item=item) + return {'statusCode': 200, 'body': json.dumps(item)} + result = table.scan() + return {'statusCode': 200, 'body': json.dumps(result['Items'])} + EOF + } + } + + resource "aws_iam_role" "lambda_role" { + name = "lambda-role" + assume_role_policy = jsonencode({ + Version = "2012-10-17" + Statement = [{ Action = "sts:AssumeRole", Effect = "Allow", + Principal = { Service = "lambda.amazonaws.com" } }] + }) + } + + resource "aws_lambda_function" "messages_api" { + function_name = "messages-api" + runtime = "python3.12" + handler = "handler.handler" + filename = data.archive_file.lambda.output_path + source_code_hash = data.archive_file.lambda.output_base64sha256 + role = aws_iam_role.lambda_role.arn + environment { + variables = { TABLE_NAME = aws_dynamodb_table.messages.name } + } + } + + resource "aws_lambda_function_url" "messages_api" { + function_name = aws_lambda_function.messages_api.function_name + authorization_type = "NONE" + } + + output "function_url" { + value = aws_lambda_function_url.messages_api.function_url + } + TF + cd /tmp/localstack-demo + ``` + + 2. Initialize and apply the configuration: + + ```bash + lstk terraform init && lstk terraform apply -auto-approve + ``` + + 3. Retrieve the endpoint: + + ```bash + LAMBDA_URL=$(lstk terraform output -raw function_url) + echo $LAMBDA_URL + ``` + + + + + +## Step 3: Test the API + +Send a POST request to store a message in the locally emulated DynamoDB table: + +```bash +curl -X POST "$LAMBDA_URL" \ + -H "Content-Type: application/json" \ + -d '{"message": "Hello, LocalStack!"}' +``` + +You will get back a response: + +```json title="Output" +{ + "id": "3e1b5cae-4386-447b-8567-f0615fdb0fff", + "message": "Hello, LocalStack!" +} +``` + +Retrieve all your messages: + +```bash +curl "$LAMBDA_URL" +``` + +The Lambda function executes within the local environment and interacts with the locally emulated DynamoDB service. +Because no actual cloud resources are created, you won't incur any real AWS cloud costs or infrastructure changes. + +## Step 4: Inspect resources + +View the state of your local infrastructure via the [LocalStack Web Application](https://app.localstack.cloud/). +Navigate to the [Stack Overview](https://app.localstack.cloud/inst/default/overview) to inspect your running resources, which are the Lambda function and DynamoDB table you just deployed. You can expand each service to see the details of the deployed resources. +![Inspect Resources using LocalStack Web Application](/images/aws/stack-overview.jpg) + +## Step 5 (Optional): Continue with the Quick Start guide + +There's a lot more you can do with LocalStack than just emulate AWS services. To learn more about how LocalStack can help you inspect, manage, snapshot, and debug your AWS project, check out the [local development quick start guide](/aws/quickstart-library/local-development/) to continue the tutorial (be sure to skip the cleanup step below). + +## Step 6: Clean up + +Stop your LocalStack container to remove all emulated resources. LocalStack is ephemeral by default; stopping the instance clears the state. + +{/* prettier-ignore-start */} + + + + ```bash + lstk stop + ``` + + + + +{/* prettier-ignore-end */} + +To persist resource state, like S3 buckets or DynamoDB tables, across restarts, check out our [state management tools](/aws/capabilities/state-management/). + +Remove the local files you created in this guide: + +```bash +rm -rf /tmp/localstack-demo +``` + +## Next steps + +You have successfully deployed and tested a serverless API on your local workstation. +Proceed to the [CI/CD guide](/aws/getting-started/ci-cd/) to learn how to integrate LocalStack into your automated continuous integration (CI) pipelines across a wide range of providers and platforms. diff --git a/src/content/docs/aws/getting-started/quickstart.mdx b/src/content/docs/aws/getting-started/quickstart.mdx deleted file mode 100644 index d512d8bf..00000000 --- a/src/content/docs/aws/getting-started/quickstart.mdx +++ /dev/null @@ -1,364 +0,0 @@ ---- -title: Quickstart -description: How to run an AWS application on your local machine and test local cloud development with LocalStack. -template: doc -sidebar: - order: 4 ---- -import { Code, LinkButton, Tabs, TabItem } from '@astrojs/starlight/components'; - -## Introduction - -In this quickstart guide, we'll walk you through the process of starting LocalStack on your local machine and deploying a [serverless image resizer application](https://github.com/localstack-samples/sample-serverless-image-resizer-s3-lambda) that utilizes several AWS services. -This guide aims to help you understand how to use LocalStack for the development and testing of your AWS applications locally. -It introduces you to the following key concepts: - -- Starting a LocalStack instance on your local machine. -- Deploying an AWS serverless application infrastructure locally. -- Running an automated integration test suite against local infrastructure. -- Exploring the LocalStack Web Application to view deployed resources. -- Destroying the local infrastructure you have provisioned. - -## Architecture - -The following diagram shows the architecture that we will deploy locally using LocalStack: - -![An AWS architecture demonstrating a sample serverless image resizer application](https://user-images.githubusercontent.com/3996682/229322761-92f52eec-5bfb-412a-a3cb-8af4ee1fed24.png) - -The architecture: - -- Configures S3 bucket notifications to invoke a Lambda function. -- Provides S3 pre-signed POST URLs for direct uploads to the S3 bucket. -- Creates S3 website hosting for serving the static application client. -- Configures direct invocation URLs for Lambda functions accessible to the client. -- Establishes Lambda SNS to SNS topic notifications for failure handling. -- Creates SNS to SES subscriptions for email notifications triggered by specific events. - -An internal SES LocalStack testing endpoint (`/_localstack/aws/ses`) is configured as well, to test email sending functionality while running our local integration test suite. - -## Prerequisites - -- [LocalStack CLI](/aws/getting-started/installation/#installing-localstack-cli) -- [LocalStack account](https://www.localstack.cloud/pricing) & [Auth Token](/aws/getting-started/auth-token/) -- [Docker](https://docs.docker.com/get-docker/) -- [Python 3.11+](https://www.python.org/downloads/) & `pip` -- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) & [`awslocal` wrapper](/aws/connecting/aws-cli/#localstack-aws-cli-awslocal) -- `jq`, `zip` & `curl` - -You can start LocalStack using the `localstack` CLI. -Start the LocalStack for AWS container with your `LOCALSTACK_AUTH_TOKEN` pre-configured: - - - - \nlocalstack start`} lang="shell" /> - - - \nlocalstack start`} lang="shell" /> - - - -If you prefer running LocalStack in detached mode, you can add the `-d` flag to the `localstack start` command, and use Docker Desktop to view the logs. - -## Instructions - -To get started, clone the sample application repository from GitHub: - -```bash -git clone https://github.com/localstack-samples/sample-serverless-image-resizer-s3-lambda.git -cd sample-serverless-image-resizer-s3-lambda -``` - -You can now follow the instructions below to start LocalStack, deploy the sample application, and test the application. - -### Setup a virtual environment - -To deploy the sample application, you need to have specific Python packages are installed. -It is advisable to utilize a virtual environment for the installation process, allowing the packages to be installed in an isolated environment. -Execute the following commands to create a virtual environment and install the packages in `requirements-dev.txt`: - - - - ```shell - python -m venv .venv - source .venv/bin/activate - pip install -r requirements-dev.txt - ``` - - - ```shell - python -m venv .venv - .venv\Scripts\activate - pip install -r requirements-dev.txt - ``` - - - -:::tip -If you are encountering issues with the installation of the packages, such as Pillow, ensure you use the same version as the Python Lambdas (3.11.6) for Pillow to work. -If you're using pyenv, install and activate Python 3.11 with the following commands: -```bash -pyenv install 3.11 -pyenv global 3.11 -``` -::: - -### Setup the serverless image resizer - -This application enables serverless image resizing using [S3](/aws/services/s3/), [SSM](/aws/services/ssm/), [Lambda](/aws/services/lambda/), [SNS](/aws/services/sns/), and [SES](/aws/services/ses/). -A simple web interface allows users to upload and view resized images. -A Lambda function generates S3 pre-signed URLs for direct uploads, while S3 bucket notifications trigger image resizing. -Another Lambda function lists and provides pre-signed URLs for browser display. -The application also handles Lambda failures through SNS and SES email notifications. - -The sample application uses AWS CLI and our `awslocal` wrapper to deploy the application to LocalStack. -Before going further, you need to build your Lambda functions. -You can use the following script that will cover all three of them: - -```bash -deployment/build-lambdas.sh -``` - -You can now deploy the sample application on LocalStack by running the following command: - -```bash -deployment/awslocal/deploy.sh -``` - -Alternatively, you can follow these instructions to deploy the sample application manually step-by-step. - -:::tip -In absence of the `awslocal` wrapper, you can use the `aws` CLI directly, by configuring an [endpoint URL](/aws/connecting/aws-cli/#configuring-an-endpoint-url) or a [custom profile](/aws/connecting/aws-cli/#configuring-a-custom-profile) like `localstack`. -You can then swap `awslocal` with `aws --endpoint-url=http://localhost:4566` or `aws --profile=localstack` in the commands below. -::: - -#### Create the S3 buckets - -```bash -awslocal s3 mb s3://localstack-thumbnails-app-images -awslocal s3 mb s3://localstack-thumbnails-app-resized -``` - -#### Add bucket names into the parameter store - -```bash -awslocal ssm put-parameter \ - --name /localstack-thumbnail-app/buckets/images \ - --type "String" \ - --value "localstack-thumbnails-app-images" -awslocal ssm put-parameter \ - --name /localstack-thumbnail-app/buckets/resized \ - --type "String" \ - --value "localstack-thumbnails-app-resized" -``` - -#### Create SNS DLQ Topic for failed lambda invocations - -```bash -awslocal sns create-topic --name failed-resize-topic -``` - -To receive immediate alerts in case of image resize failures, subscribe an email address to the system. -You can use the following command to subscribe an email address to the SNS topic: - -```bash -awslocal sns subscribe \ - --topic-arn arn:aws:sns:us-east-1:000000000000:failed-resize-topic \ - --protocol email \ - --notification-endpoint my-email@example.com -``` - -#### Create the Presign Lambda - -```bash showshowLineNumbers -(cd lambdas/presign; rm -f lambda.zip; zip lambda.zip handler.py) -awslocal lambda create-function \ - --function-name presign \ - --runtime python3.11 \ - --timeout 10 \ - --zip-file fileb://lambdas/presign/lambda.zip \ - --handler handler.handler \ - --role arn:aws:iam::000000000000:role/lambda-role \ - --environment Variables="{STAGE=local}" -awslocal lambda wait function-active-v2 --function-name presign -awslocal lambda create-function-url-config \ - --function-name presign \ - --auth-type NONE -``` - -#### Create the Image List Lambda - -```bash showshowLineNumbers -(cd lambdas/list; rm -f lambda.zip; zip lambda.zip handler.py) -awslocal lambda create-function \ - --function-name list \ - --handler handler.handler \ - --zip-file fileb://lambdas/list/lambda.zip \ - --runtime python3.11 \ - --timeout 10 \ - --role arn:aws:iam::000000000000:role/lambda-role \ - --environment Variables="{STAGE=local}" -awslocal lambda wait function-active-v2 --function-name list -awslocal lambda create-function-url-config \ - --function-name list \ - --auth-type NONE -``` - -#### Build the Image Resizer Lambda - - - - ```bash showshowLineNumbers - cd lambdas/resize - rm -rf libs lambda.zip - docker run --platform linux/x86_64 -v "$PWD":/var/task "public.ecr.aws/sam/build-python3.11" /bin/sh -c "pip install -r requirements.txt -t libs; exit" - cd libs && zip -r ../lambda.zip . && cd .. - zip lambda.zip handler.py - rm -rf libs - cd ../.. - ``` - - - ```bash showshowLineNumbers - cd lambdas/resize - rm -rf package lambda.zip - mkdir package - pip install -r requirements.txt -t package --platform manylinux_2_28_x86_64 --python-version 3.11 --no-deps - zip lambda.zip handler.py - cd package - zip -r ../lambda.zip *; - cd ../.. - ``` - - - ```bash showshowLineNumbers - cd lambdas/resize - rm -rf package lambda.zip - mkdir package - pip install -r requirements.txt -t package - zip lambda.zip handler.py - cd package - zip -r ../lambda.zip\_; - cd ../.. - ``` - - - -#### Create the Image Resizer Lambda - -```bash showshowLineNumbers -awslocal lambda create-function \ - --function-name resize \ - --runtime python3.11 \ - --timeout 10 \ - --zip-file fileb://lambdas/resize/lambda.zip \ - --handler handler.handler \ - --dead-letter-config TargetArn=arn:aws:sns:us-east-1:000000000000:failed-resize-topic \ - --role arn:aws:iam::000000000000:role/lambda-role \ - --environment Variables="{STAGE=local}" -awslocal lambda wait function-active-v2 --function-name resize -awslocal lambda put-function-event-invoke-config \ - --function-name resize \ - --maximum-event-age-in-seconds 3600 \ - --maximum-retry-attempts 0 -``` - -#### Connect S3 bucket to Resizer Lambda - -```bash -awslocal s3api put-bucket-notification-configuration \ - --bucket localstack-thumbnails-app-images \ - --notification-configuration "{\"LambdaFunctionConfigurations\": [{\"LambdaFunctionArn\": \"$(awslocal lambda get-function --function-name resize --output json | jq -r .Configuration.FunctionArn)\", \"Events\": [\"s3:ObjectCreated:*\"]}]}" -``` - -#### Create the S3 static website - -```bash -awslocal s3 mb s3://webapp -awslocal s3 sync --delete ./website s3://webapp -awslocal s3 website s3://webapp --index-document index.html -``` - -#### Retrieve the Lambda Function URLs - -Retrieve the Lambda function URLs for the `presign` and `list` Lambda functions using the following commands: - -```bash -awslocal lambda list-function-url-configs --function-name presign --output json | jq -r '.FunctionUrlConfigs[0].FunctionUrl' -awslocal lambda list-function-url-configs --function-name list --output json | jq -r '.FunctionUrlConfigs[0].FunctionUrl' -``` - -Save these URLs for later use in the sample application. - -### Run the sample AWS application - -To access the application, go to [**https://webapp.s3-website.localhost.localstack.cloud:4566**](https://webapp.s3-website.localhost.localstack.cloud:4566) in your browser. - -![Serverless image resizer application](/images/aws/serverless-image-resizer-application.png) - -Paste the `presign` and `list` Lambda function URLs into the application and click **Apply**. -Alternatively, click on **Load from API** to automatically load the URLs. - -Upload an image, and click **Upload**. -The upload form uses the `presign` Lambda to request an S3 pre-signed POST URL, forwarding the POST request to S3. -Asynchronous resizing (maximum 400x400 pixels) occurs through S3 bucket notifications. - -If successful, the application displays a **success!** alert. -Click **Refresh** to trigger your browser to request the `list` Lambda URL, returning a JSON document of all items in the images (`localstack-thumbnails-app-images`) and resized images (`localstack-thumbnails-app-resized`) bucket. - -![Serverless image resizer application displaying a resized image](/images/aws/resized-image-sample-application.png) - -### View the deployed resources - -You can inspect the resources deployed as part of the sample application by accessing the [**LocalStack Web Application**](https://app.localstack.cloud/). -Navigate to your [**Default Instance**](https://app.localstack.cloud/inst/default/status) to view the deployed resources. - -![Status Page of the LocalStack Web Application"](/images/aws/localstack-web-application-status.png) - -Click on [S3](https://app.localstack.cloud/inst/default/resources/s3) or [Lambda](https://app.localstack.cloud/inst/default/resources/lambda/functions) to view the S3 buckets and Lambda functions respectively. - -![The Lambda Resource Browser Page of the LocalStack Web Application](/images/aws/localstack-web-application-lambda.png) - -### Run integration tests - -To run automated integration tests against the sample application, use the following command: - -```bash -pytest -v -``` - -Additionally, you can verify that when the `resize` Lambda fails, an SNS message is sent to a topic that an SES subscription listens to, triggering an email with the raw failure message. -Since there's no real email server involved, you can use the LocalStack SES developer endpoint to list messages sent via SES: - -```bash -curl -s http://localhost.localstack.cloud:4566/_aws/ses | jq -``` - -An alternative option is to use a service like MailHog or `smtp4dev`. -Start LocalStack with `SMTP_HOST=host.docker.internal:1025`, pointing to the mock SMTP server. - -### Destroy the local infrastructure - -Now that you've learned how to deploy a local AWS infrastructure for your sample application, let's clean up and tear down the resources associated with the project: - -```bash -localstack stop -``` - -LocalStack is ephemeral, meaning it doesn't persist any data across restarts. -It runs inside a Docker container, and once it's stopped, all locally created resources are automatically removed. - -To persist the local cloud resources across restarts, navigate to our [persistence documentation](/aws/developer-tools/snapshots/persistence) or learn about [Cloud Pods](/aws/developer-tools/snapshots/cloud-pods), our next generation state management utility. - -## Next Steps - -Congratulations on deploying an AWS application locally using LocalStack! -To expand your LocalStack capabilities, explore the following based on your expertise: - -- [Tutorials](/aws/tutorials): Check out our tutorials to learn how to use LocalStack across various AWS services and application stacks. -- [Supported Services](/aws/services): Explore LocalStack's emulated AWS services. -- [Connecting](/aws/connecting/): Connect to LocalStack from the AWS CLI, SDKs, IaC tools, IDEs, and the web Console. -- [Developer Tools](/aws/developer-tools/): Use LocalStack's tooling, including App Inspector, Cloud Pods, Chaos Engineering, and the Lambda developer tools. -- [CI Pipelines](/aws/ci-pipelines/): Run LocalStack in your CI pipelines for automated integration testing. -- [Customization](/aws/customization/): Customize how LocalStack behaves, from configuration options and Kubernetes to third-party integrations. -- [Organizations & Admin](/aws/organizations-admin/): Manage accounts, workspaces, users, licenses, and single sign-on for your team. -- [Blog](https://blog.localstack.cloud): Read our blog posts about LocalStack and the latest enhancements for a better local development and testing experience. diff --git a/src/content/docs/aws/quickstart-library/index.mdx b/src/content/docs/aws/quickstart-library/index.mdx new file mode 100644 index 00000000..3529f629 --- /dev/null +++ b/src/content/docs/aws/quickstart-library/index.mdx @@ -0,0 +1,23 @@ +--- +title: Overview +description: LocalStack Quickstart Library. +template: doc +sidebar: + order: 1 +--- + +import { SectionCards } from '../../../../components/SectionCards.tsx'; + +Our Quick Start Library is a growing collection of tutorials that help you get started with LocalStack. Each tutorial walks you through a specific use case or feature of LocalStack. + + diff --git a/src/content/docs/aws/quickstart-library/local-development.mdx b/src/content/docs/aws/quickstart-library/local-development.mdx new file mode 100644 index 00000000..1b274333 --- /dev/null +++ b/src/content/docs/aws/quickstart-library/local-development.mdx @@ -0,0 +1,240 @@ +--- +title: Local Development +description: Use the LocalStack Web Application to inspect, browse, snapshot, and trace the serverless API you deployed in the Local Development tutorial. +template: doc +sidebar: + order: 2 +--- + +import { Steps } from '@astrojs/starlight/components'; + +## Introduction + +The [Getting Started - Local Development](/aws/getting-started/local-development/) tutorial walked you through deploying a Lambda function and a DynamoDB table on LocalStack, then testing it with `curl`. Everything up to that point happened on the command line. + +This quickstart picks up where that tutorial left off and shows the tools you can leverage to inspect, manage, snapshot, and debug your LocalStack instance. You will use the [LocalStack Web Application](https://app.localstack.cloud/) to: + +1. Confirm your local instance is running and find it in the browser. +2. Get a visual summary of your deployed resources with **Stack Overview**. +3. Trigger your Lambda function and browse the resulting DynamoDB rows with the **Resource Browser**. +4. Snapshot the entire application state, wipe it, and bring it back with **Cloud Pods**. +5. Trace the request flow between your Lambda function and DynamoDB table with **App Inspector**. + +By the end, you will be comfortable using the web application to enhance your workflow for local development, alongside the CLI tools you already know. + +## Prerequisites + +- Completed the [Getting Started - Local Development](/aws/getting-started/local-development/) tutorial, **without** running its Step 6 cleanup. Your `messages-api` Lambda function and `Messages` DynamoDB table should still be deployed. +- The LocalStack container from that tutorial still running. If you closed your terminal, the container keeps running in the background โ€” verify with: + + ```bash + lstk status + ``` + + If it reports that the AWS emulator is not running, start it again with `lstk start`. Since LocalStack is ephemeral by default, this gives you a fresh, empty instance โ€” redeploy the Lambda function and DynamoDB table from the tutorial before continuing. + +- Signed in to the [LocalStack Web Application](https://app.localstack.cloud/). + +## Step by Step + +### Step 1: Find your running instance + +Before opening the browser, confirm LocalStack is actually up and check what it currently has deployed: + +```bash +lstk status +``` + +```text title="Output" +LocalStack AWS Emulator is running +โ€ข Endpoint: localhost:4566 +โ€ข Container: localstack-main +โ€ข Version: 4.9.1 +โ€ข Uptime: 12m 3s + +~ 2 resources ยท 2 services + +Service Resource Region Account +Lambda messages-api us-east-1 000000000000 +DynamoDB Messages us-east-1 000000000000 +``` + + + +1. Open the [LocalStack Web Application](https://app.localstack.cloud/) and sign in. +2. In the sidebar, under **LocalStack Instances**, click on your running instance (e.g. `localhost.localstack.cloud`). The instance should display a green **running** badge. + ![LocalStack Web Application sidebar showing a running instance](/images/aws/running-instance-sidebar.jpg) + + + +**Expected result:** the instance card shows a green **running** badge. Clicking into it opens the instance dashboard with tabs for **Overview**, **Status**, **Resource Browser**, **State**, and **Extensions**. The default tab is **Resource Browser**, which displays a list of all the resources you can inspect via the web application. + +If you don't see a running instance, see [Troubleshooting](#troubleshooting) before continuing. + +### Step 2: Inspect your app with Stack Overview + +Stack Overview gives you a summary of everything deployed on the instance. + + + +1. From the instance dashboard, click the [**Overview** tab](https://app.localstack.cloud/inst/default/overview). +2. Look for the **Lambda Function** and **DynamoDB Table** items in the list. +3. Click the arrow (`>`) next to **Lambda Function** to expand it and confirm `messages-api` is listed. Do the same for **DynamoDB Table** to confirm the `Messages` table is deployed. + + + +![Stack Overview showing deployed resource types with counts](/images/aws/stack-overview.jpg) + +:::note +Stack Overview is a **preview** feature. It only tracks a defined set of [supported resource types](/aws/connecting/console/stack-overview/#supported-resources). Lambda functions and DynamoDB tables are both covered, but if you extend this app with a service that isn't on the list, it won't show up here even though it's running fine. +::: + +**Expected result:** you can confirm, at a glance, that both the Lambda function and the DynamoDB table from the tutorial are deployed without needing to use the CLI. + +### Step 3: Trigger the Lambda and inspect data with the Resource Browsers + +Many supported services in LocalStack for AWS come with a resource browse that allows you to view configuration details and manage individual resources. Use it here to check the Lambda function's configuration, trigger the function, and then validate that a new row lands in DynamoDB. + + + +1. Navigate to the [**Status** tab](https://app.localstack.cloud/inst/default/status). It displays a list of the running services at the top as well as additional services that are available to use within the LocalStack emulator. +2. Under **Running** services, click **Lambda**, then, within the **Functions** tab, and click the `messages-api` function. From here you can review the function's details including the ARN, runtime, handler, and the `TABLE_NAME` environment variable pointing at `Messages`. You can also update the function code, invoke the function, and view the function logs. + ![Lambda Resource Browser showing the details of a deployed Lambda function](/images/aws/lambda-resource-browser.jpg) +3. Click **Invoke** to open the invoke dialog and paste the following JSON payload into the input field: + ```json + { + "message": "Checked out from the Resource Browser" + } + ``` +4. Click **Submit** to trigger the function. You will see the function invoked and the response returned. The log result of the response should look like this: + + ```json title="Output" + { + "statusCode": 200, + "body": { + "id": "faa4dc54-f0b7-4b6b-9e52-39702af78d73", + "message": "Checked out from the Resource Browser" + } + } + ``` + + + +With the Lambda invoked, switch to the DynamoDB side to see what it wrote: + + + +1. Back in the [**Status** tab](https://app.localstack.cloud/inst/default/status) and click on **DynamoDB** and then, fromthe **Tables** tab, click the `Messages` table. This will open the table details page where you can view the table's details including the table name, key schema, and the number of items in the table. +2. Click the **Items** tab to view the table's contents. You should see the message you posted during the tutorial _and_ the new one you just sent. + ![DynamoDB Resource Browser showing the Items list](/images/aws/dynamodb-resource-browser.jpg) + + + +**Expected result:** the Items view for the DynamoDB "Messages" table lists the message you posted during the tutorial _and_ the new one you just sent confirming that the Lambda function is writing to the table. + +:::tip +If the table doesn't appear, check the **region** dropdown in the top-right corner of the Resource Browser. It must match the region your resources were created in (`us-east-1` by default in the tutorial). +::: + +### Step 4: Save and restore state with Cloud Pods + +[Cloud Pods](/aws/developer-tools/snapshots/cloud-pods/) let you snapshot your entire LocalStack state, including resources _and_ their data, and restore it later or share it with your team. You can save a Cloud Pod and view saved pods using the web application or CLI. Try this by saving your current app, wiping it, and restoring it via the web application. + + + +1. In your instance dashboard, click the **State** tab and then click the **Cloud** view. +2. Under **Save State to Cloud Pod**, enter `messages-api-demo` for the pod name. Leave the other options as default and click **Create New Pod**. + ![Cloud Pods Save State to Cloud Pod dialog](/images/aws/export-cloud-pod-web-app.jpg) +3. Verify it in the web application by navigating to **Cloud Pods** in the sidebar (`https://app.localstack.cloud/pods`). You should see `messages-api-demo` listed with a version `1`. + ![Cloud Pods Browser listing saved Cloud Pods](/images/aws/verify-cloud-pod-save.jpg) + + + +Now let's clear the instance and confirm it's actually gone and then restore it: + + + +1. Reset the LocalStack instance: + + ```bash + lstk reset + ``` + +2. Back in the [**Stack Overview** tab](https://app.localstack.cloud/inst/default/overview), confirm the `messages-api` function and `Messages` table are no longer listed. LocalStack is ephemeral by default, so restarting the container discards everything. + +3. Switch back to the [**State** tab](https://app.localstack.cloud/inst/default/state) and click the **Cloud** view. Under **Load State from Cloud Pod**, select `messages-api-demo` from the dropdown. You should see details about the pod displayed. Leave the default merge strategy (to learn more about merge strategies, see the [Cloud Pods documentation](https://docs.localstack.cloud/aws/developer-tools/snapshots/cloud-pods/#state-merging)) and click **Load State from Pod**. + ![Cloud Pods Load State from Cloud Pod dialog](/images/aws/load-state-from-pod.jpg) + + + +**Expected result:** Return to the [**Stack Overview** tab](https://app.localstack.cloud/inst/default/overview) again. You should see the `messages-api` and `Messages` tables are back. Opening the DynamoDB table in the resource browser and clicking the **Items** tab will show the items you saved before the restart are back as well. Cloud Pods restored the _data_ in the table, not just the table definition. + +:::note +You can do the same save/restore flow from `lstk` instead of the web applicatin using the `lstk snapshot save` and `lstk snapshot load` commands. For more details, see the [lstk documentation](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/#snapshot). +::: + +### Step 5: Trace the request flow with App Inspector + +[App Inspector](/aws/developer-tools/app-inspector/) records every call your application makes to LocalStack, so you can see the flow between services, inspect the exact payloads exchanged, and catch IAM or configuration issues before they become deployment surprises. + + + +1. Navigate to [**App Inspector** tab](https://app.localstack.cloud/inst/default/appinspector/spans?region=us-east-1) for your instance. +2. App Inspector hasn't been enabled on this instance yet, so click the **Enable App Inspector Now** button to enable it. You won't see any operations listed yet. +3. Fetch a fresh function URL, then trigger the Lambda: + + ```bash + LAMBDA_URL=$(lstk aws lambda list-function-url-configs \ + --function-name messages-api \ + --query 'FunctionUrlConfigs[0].FunctionUrl' \ + --output text) + echo $LAMBDA_URL + + curl -X POST "$LAMBDA_URL" \ + -H "Content-Type: application/json" \ + -d '{"message": "Hello, App Inspector!"}' + ``` + +4. Return to the App Inspector tab and you should see the operations listed. This is a simple demo, so you'll only see two operations: one to get the function URL and one to invoke the function. + ![App Inspector event list showing a request flow across services](/images/aws/app-inspector-operations.jpg) + + + +**Expected result:** App Inpsector correctly captures the two operations you triggered. Clicking on an operation will open the operation details panel. This will show a diagram of the request flow and the service, action, resource ARN, duration, status, and the exact request/response payload. In this case, the operations details are extremely simple and don't show any errors, but this kind of detail is invaluable for debugging and understanding the flow of your application. + +:::note +App Inspector requires LocalStack **2026.04.0** or later. If you don't see it in the sidebar, check your version with `lstk status` and update your image. +::: + +## Troubleshooting + +**Instance shows as "not running" in Instance Management** +Run `lstk status` from your terminal to confirm the container's actual state, and check that Docker is running. Start it again with `lstk start` if needed โ€” remember this gives you an empty instance unless you load a Cloud Pod afterwards. + +**Resource Browser shows a "Network Failure" error** +The LocalStack container isn't running, or isn't reachable at the endpoint configured for the instance. Confirm the endpoint in Instance Management matches your running container (`https://localhost.localstack.cloud:4566` by default). Ensure that you have enabled **Private Network Access** if you are using Google Chrome (see [Troubleshooting](https://docs.localstack.cloud/aws/getting-started/faq/#why-cant-i-access-my-localstack-instance-in-the-web-application-when-using-chrome) for more details). + +**Lambda function or DynamoDB table don't appear anywhere in the web app** +Check the region dropdown in the top-right of the Resource Browser. If it's set to a region other than the one you deployed to (`us-east-1` by default in the tutorial), switch it. + +**Resources are missing after a restart, even though you didn't mean to wipe them** +LocalStack does not persist state across restarts by default. Either avoid stopping the container, enable [persistence](https://docs.localstack.cloud/aws/developer-tools/snapshots/persistence/), or restore your last Cloud Pod with `lstk snapshot load pod:`. + +**`lstk snapshot save` fails with an authentication or license error** +Cloud Pods require a valid LocalStack account. Run `lstk login`, or confirm `LOCALSTACK_AUTH_TOKEN` is set correctly, and try again. + +**`lstk snapshot load` warns about a version mismatch** +This happens when the LocalStack version that saved the pod differs from the one running now. It's safe to proceed for this demo; in real projects, pin your LocalStack version to avoid state incompatibilities. + +## Next steps + +You've now used all four core areas of the LocalStack Web Application to inspect, manage, snapshot, and debug a running application. To go deeper on any of them: + +- [Instance Management](https://docs.localstack.cloud/aws/connecting/console/instance-management/) โ€” bookmarking instances and connecting to a LocalStack instance running on another machine. +- [Stack Overview](https://docs.localstack.cloud/aws/connecting/console/stack-overview/) โ€” the full list of supported resource types. +- [Resource Browser](https://docs.localstack.cloud/aws/connecting/console/resource-browser/) โ€” the complete list of supported services beyond Lambda and DynamoDB. +- [Cloud Pods](https://docs.localstack.cloud/aws/developer-tools/snapshots/cloud-pods/) โ€” merge strategies, remotes, auto-loading pods on startup, and sharing state with your team. +- [App Inspector](https://docs.localstack.cloud/aws/developer-tools/app-inspector/) โ€” using it from the [LocalStack Toolkit for VS Code](https://docs.localstack.cloud/aws/connecting/ides/vscode-extension/) without leaving your editor. +- [`lstk` CLI reference](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/) โ€” the full set of `snapshot`, `status`, and `reset` commands used in this guide. + +Once you're comfortable with the local workflow, continue to the [CI/CD guide](https://docs.localstack.cloud/aws/getting-started/ci-cd/) to bring LocalStack into your automated pipelines. diff --git a/src/content/docs/aws/services/ec2.mdx b/src/content/docs/aws/services/ec2.mdx index 677782fc..c4a67296 100644 --- a/src/content/docs/aws/services/ec2.mdx +++ b/src/content/docs/aws/services/ec2.mdx @@ -494,7 +494,7 @@ If you are using the [Docker Compose template](/aws/getting-started/installation "/var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock" ``` -If you are using [Docker CLI](/aws/getting-started/installation#docker), include the following parameter in `docker run`: +If you are using [Docker CLI](/aws/getting-started/installation#docker-cli), include the following parameter in `docker run`: ```text -v /var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock diff --git a/src/content/docs/aws/services/lambda.mdx b/src/content/docs/aws/services/lambda.mdx index df73abc5..e659e278 100644 --- a/src/content/docs/aws/services/lambda.mdx +++ b/src/content/docs/aws/services/lambda.mdx @@ -589,7 +589,7 @@ With the new implementation, the following changes have been introduced: - To run Lambda functions in LocalStack, mount the Docker socket into the LocalStack container. Add the following Docker volume mount to your LocalStack startup configuration: `/var/run/docker.sock:/var/run/docker.sock`. - You can find an example of this configuration in our official [`docker-compose.yml` file](/aws/getting-started/installation/#starting-localstack-with-docker-compose). + You can find an example of this configuration in our official [`docker-compose.yml` file](/aws/getting-started/installation/#docker-compose). - The `v2` provider discontinues Lambda Executor Modes such as `LAMBDA_EXECUTOR=local`. Previously, this mode was used as a fallback when the Docker socket was unavailable in the LocalStack container, but many users unintentionally used it instead of the configured `LAMBDA_EXECUTOR=docker`. The new provider now behaves similarly to the old `docker-reuse` executor and does not require such configuration. diff --git a/src/styles/custom.css b/src/styles/custom.css index c5839b94..14a36c63 100644 --- a/src/styles/custom.css +++ b/src/styles/custom.css @@ -24,6 +24,19 @@ vertical-align: middle; } +.lightning-icon::before { + content: ""; + display: inline-block; + width: 16px; + height: 16px; + background-image: url('/src/assets/images/lightning.svg'); + background-size: contain; + background-repeat: no-repeat; + background-position: center; + margin-right: 6px; + vertical-align: middle; +} + .file-icon::before { content: ""; display: inline-block;