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..51efca9d --- /dev/null +++ b/src/content/docs/aws/getting-started/ai-workflows.mdx @@ -0,0 +1,95 @@ +--- +title: AI & Agent Workflows +description: Use LocalStack with AI coding assistants, MCP servers, and agent-driven infrastructure automation. +template: doc +sidebar: + order: 5 +--- + +## Overview + +AI-assisted development workflows need a fast and secure environment to develop and test in. +Whether you're using an AI coding assistant to generate infrastructure code, running an agent that deploys AWS resources, or validating AI-generated IaC before applying it to real AWS — LocalStack gives you a safe, fast, cost-free environment to run these workflows in. + +## Connect an AI coding assistant via MCP + +The [LocalStack MCP Server](https://github.com/localstack/localstack-mcp-server) is a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that connects compatible clients (Claude, Cursor, Windsurf, and others) to your LocalStack environment. +It gives agents tools to run the full local cloud lifecycle—not only generating infrastructure code, but starting the container, deploying and tearing down IaC, analyzing logs, and more. +See [Introducing the LocalStack MCP Server](https://blog.localstack.cloud/introducing-localstack-mcp-server/) for the original announcement and walkthrough. + +With the MCP server configured, your assistant can use tools such as: + +- **Lifecycle** — Start, stop, restart, or check status of the LocalStack container +- **Deploy** — Deploy or destroy CDK, Terraform, SAM, or CloudFormation projects on LocalStack +- **Operations** — Analyze logs, run AWS CLI commands via `awslocal`, manage [Cloud Pods](/aws/capabilities/state-management/cloud-pods/), and (where supported) IAM policy analysis, chaos injection, and docs search + +...and many more. + +### MCP Server Prerequisites + +Before you begin, make sure these are installed and in your system's `PATH`: + +- [Node.js](https://nodejs.org/en/) (v20.x or later) to run the `npx` command. +- [LocalStack CLI](https://docs.localstack.cloud/user-guide/cli/) and [Docker](https://docs.docker.com/get-docker/) to manage the LocalStack container itself. +- [`cdklocal`](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/) or [`tflocal`](https://docs.localstack.cloud/user-guide/integrations/terraform/) to use the `localstack-deployer` tool. (optional) +- A [LocalStack Auth Token](https://docs.localstack.cloud/getting-started/auth-token/) to enable licensed features. (optional) + +### MCP Server Configuration + +Add a server entry like this to your client's MCP configuration—for **Cursor**, this would typically be `~/.cursor/mcp.json`. +For **Claude Code**, register the server with `claude mcp add` (it is saved to your project-level MCP configuration). + +```json +{ + "mcpServers": { + "localstack-mcp-server": { + "command": "npx", + "args": ["-y", "@localstack/localstack-mcp-server"], + "env": { + "LOCALSTACK_AUTH_TOKEN": "" + } + } + } +} +``` + +Full prerequisites, Cursor/VS Code/Claude Code variants, custom endpoints (`LOCALSTACK_HOSTNAME`, `LOCALSTACK_PORT`), troubleshooting, and the complete tool reference are on [LocalStack MCP Server](/aws/tooling/mcp-server/). + +:::note +You do not need to start LocalStack manually before using MCP: an agent can start the container using the **localstack-management** tool once this configuration is in place. +If LocalStack already runs elsewhere, point the MCP server at it via the `env` block as described in [Connecting to a custom LocalStack endpoint](/aws/tooling/mcp-server/#connecting-to-a-custom-localstack-endpoint). +::: + +## Deploy with agent-driven automation using Skills + +[LocalStack Skills](https://github.com/localstack/skills) are pre-built agent skill definitions for deploying common AWS architectures locally. It contains skills for LocalStack lifecycle management, IaC deployment, state management and more. Skills can be used in combination with the MCP server to create a fully autonomous agent-driven workflow. + +Skills are useful when: + +- You want to scaffold a new local environment quickly without writing all the infrastructure code yourself +- You're using an agent-first workflow and want LocalStack to be a first-class deployment target +- You want to iterate rapidly on architecture without touching real AWS + +Browse the [skills repository](https://github.com/localstack/skills) for available skills and setup instructions. + +## Validate AI-generated IaC before applying to AWS + +A common pattern when using AI to generate Terraform, CDK, or CloudFormation is to deploy it to LocalStack first. +This catches configuration errors, missing permissions, and service interaction bugs before you spend time (and money) deploying to real AWS. + +The workflow is: + +1. Generate infrastructure code with your AI tool +2. Deploy to LocalStack with `tflocal apply` (Terraform), `cdklocal deploy` (CDK), or the AWS CLI +3. Run your integration tests against the local environment +4. When everything passes, deploy to real AWS with confidence + +See [Tooling](/aws/tooling/) for the full list of LocalStack-aware wrappers for common IaC tools. + +## Summary + +| Use case | Tool | +| ------------------------------------------------------ | --------------------------------------------------------- | +| AI assistant that can inspect & manage local resources | [LocalStack MCP Server](/aws/tooling/mcp-server/) | +| Agent-driven infrastructure deployment | [LocalStack Skills](https://github.com/localstack/skills) | +| Validate AI-generated IaC safely | LocalStack + `tflocal` / `cdklocal` / `awslocal` | diff --git a/src/content/docs/aws/getting-started/auth-token.mdx b/src/content/docs/aws/getting-started/auth-token.mdx index b71c45a1..aea872ca 100644 --- a/src/content/docs/aws/getting-started/auth-token.mdx +++ b/src/content/docs/aws/getting-started/auth-token.mdx @@ -3,17 +3,23 @@ title: Auth Token description: Configure your Auth Token to access and activate LocalStack. template: doc sidebar: - order: 3 + order: 6 --- import { Code, Tabs, TabItem } from '@astrojs/starlight/components'; ## Introduction -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. +The Auth Token activates LocalStack for AWS. It ties the running instance to your workspace and license and is required whenever you use LocalStack for AWS. -Auth tokens come in two types: a **Developer Auth Token** and a **CI Auth Token**: +**Whether you need to configure a token by hand** depends on how you run LocalStack: + +- **[`lstk`](/aws/tooling/lstk)** (early release) — For most local development, the Auth Token is present but easy to overlook. On first run or after `lstk login`, the CLI completes a browser login flow, stores your **Developer Auth Token** in the system keyring (or a config-directory fallback when no keyring is available), and injects it into the container whenever you start LocalStack. You are still using an Auth Token for activation; `lstk` obtains and reuses it after login instead of asking you to set `LOCALSTACK_AUTH_TOKEN` yourself. +- **LocalStack CLI (`localstack`)** — You configure the token yourself: set `LOCALSTACK_AUTH_TOKEN` or run `localstack auth set-token` (see [Configuring your Auth Token](#configuring-your-auth-token)). [`lstk`](/aws/tooling/lstk) is currently in early release and missing some core features, so the `localstack` CLI is still the right tool for Cloud Pods, Extensions, Ephemeral Instances, and other advanced features, so many workflows keep using it and therefore set an Auth Token explicitly. For personal development, use your **Developer Auth Token** from the web app. +- **Docker or Docker Compose** — You pass `LOCALSTACK_AUTH_TOKEN` into the container (see [Configuring your Auth Token](#configuring-your-auth-token)). Use your **Developer Auth Token** for local runs unless you are in CI. +- **CI pipelines and other automated, non-interactive environments** — You must set `LOCALSTACK_AUTH_TOKEN` to a **CI Auth Token**. Developer Auth Tokens should not be used in CI. See [CI Environments](#ci-environments). + +Auth tokens come in two types: a **Developer Auth Token** and a **CI Auth Token**. - The **Developer Auth Token** is linked to a specific user within a specific workspace. Every user has their own Auth Token. @@ -205,25 +211,6 @@ Another way to confirm this is by checking the logs of the LocalStack container Otherwise, check our [troubleshooting](#troubleshooting) section. -## FAQ - -### How do I activate older versions of LocalStack (Before v3.0)? - -Prior to the introduction of Auth Tokens, LocalStack used **API keys** managed through the `LOCALSTACK_API_KEY` environment variable for activation. - -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. - -### When will the legacy API keys be phased out? - -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. - -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. - -The downtime schedule will be communicated well in advance, allowing users ample time to switch to the new Auth Tokens. - ## Troubleshooting While using Auth Tokens, LocalStack demands a successful license activation for startup. 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..ced79a3e --- /dev/null +++ b/src/content/docs/aws/getting-started/ci-cd.mdx @@ -0,0 +1,195 @@ +--- +title: CI/CD +description: Run LocalStack in CI pipelines — auth tokens, Docker Compose, GitHub Actions examples, and persisting state with Cloud Pods or state export. +template: doc +sidebar: + order: 4 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +## Overview + +LocalStack works great in CI environments, allowing your integration tests to run incredibly fast and with no cloud costs. +The setup differs slighty from local development in a few important ways: + +- **Use a CI Auth Token**, not your personal Developer token +- **Start LocalStack without a browser** — Docker Compose, `docker run`, or CI helpers such as [`setup-localstack`](https://github.com/localstack/setup-localstack) are common; [`lstk`](/aws/tooling/lstk/) also works in CI when you set `LOCALSTACK_AUTH_TOKEN` and use [`--non-interactive`](/aws/tooling/lstk/#interactive-and-non-interactive-mode) (or rely on automatic non-interactive detection). LocalStack Desktop remains a local-only GUI. +- **Runs are often isolated per job** — many pipelines start from an empty LocalStack instance for reproducible tests +- **Persistence in CI is supported** — [Cloud Pods](/aws/capabilities/state-management/cloud-pods/), snapshot-based [persistence](/aws/capabilities/state-management/persistence/) with a mounted volume, or `localstack state export` / `localstack state import` with artifacts or cache. + +## Step 1 — Get a CI Auth Token + +CI pipelines should use a dedicated CI Auth Token, not a developer token tied to a specific user. + +1. Go to the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application +2. Create a new **CI Auth Token** +3. Add it as a secret in your CI provider (e.g., `LOCALSTACK_AUTH_TOKEN`) + +:::danger[Keep your token secret] +Never commit an auth token to source control. +Always inject it via your CI provider's secrets or environment variable mechanism. +If a token is compromised, rotate it immediately on the Auth Tokens page — old tokens are invalidated instantly. +::: + +See the [Auth Token documentation](/aws/getting-started/auth-token/) for full details on token types and configuration. + +## Step 2 — Start LocalStack in CI + + + + The recommended approach is to start LocalStack as a service container or as a step using the official GitHub Action: + + ```yaml + # .github/workflows/integration-tests.yml + name: Integration Tests + + on: [push, pull_request] + + jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Start LocalStack + uses: LocalStack/setup-localstack@v0.2.2 + with: + image-tag: latest + install-awslocal: "true" + env: + LOCALSTACK_AUTH_TOKEN: ${{ secrets.LOCALSTACK_AUTH_TOKEN }} + + - name: Run tests + run: | + # Your test commands here, e.g.: + pip install awscli-local + awslocal s3 mb s3://my-test-bucket + pytest tests/integration/ + ``` + + The `setup-localstack` action handles pulling the image, starting the container, and waiting for LocalStack to be ready. + + + + Add LocalStack as a service in your `docker-compose.yml`: + + ```yaml + services: + localstack: + container_name: localstack-main + image: localstack/localstack-pro + ports: + - "127.0.0.1:4566:4566" + - "127.0.0.1:4510-4559:4510-4559" + - "127.0.0.1:443:443" + environment: + - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} + - DEBUG=${DEBUG:-0} + volumes: + - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" + - "/var/run/docker.sock:/var/run/docker.sock" + ``` + + Start it and wait for readiness: + + ```bash + docker compose up -d localstack + # Wait for LocalStack to be ready + until curl -s http://localhost:4566/_localstack/health | grep -q '"running"'; do sleep 1; done + ``` + + :::note + Mounting `/var/run/docker.sock` is required for Lambda emulation, which uses Docker to run function containers. + ::: + + + + Start LocalStack directly with `docker run`: + + ```bash + docker run \ + --rm -d \ + --name localstack-main \ + -p 127.0.0.1:4566:4566 \ + -p 127.0.0.1:4510-4559:4510-4559 \ + -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ + -v /var/run/docker.sock:/var/run/docker.sock \ + localstack/localstack-pro + + # Wait for readiness + until curl -s http://localhost:4566/_localstack/health | grep -q '"running"'; do sleep 1; done + ``` + + + + Add LocalStack as a service in your CircleCI config: + + ```yaml + version: 2.1 + + jobs: + integration-tests: + docker: + - image: cimg/python:3.12 + - image: localstack/localstack-pro + environment: + LOCALSTACK_AUTH_TOKEN: $LOCALSTACK_AUTH_TOKEN + steps: + - checkout + - run: + name: Wait for LocalStack + command: | + until curl -s http://localhost:4566/_localstack/health | grep -q '"running"'; do sleep 1; done + - run: + name: Run tests + command: pytest tests/integration/ + ``` + + Set `LOCALSTACK_AUTH_TOKEN` in your CircleCI project's environment variables. + + + + +## Verify activation + +After LocalStack starts, confirm the license is active: + +```bash +curl -s http://localhost:4566/_localstack/info | jq '.is_license_activated' +# Should return: true +``` + +## Key differences from local development + +| | Local development | CI/CD | +| -------------- | -------------------------------- | ----------------------------------------------------------------------------------- | +| **CLI** | `lstk` or LocalStack CLI | Docker Compose / `docker run`, or `lstk --non-interactive` | +| **Auth** | Browser login or stored token | `LOCALSTACK_AUTH_TOKEN` env var | +| **Token type** | Developer token | CI token | +| **State** | Optional persistence | Optional persistence (same mechanisms; typical pattern is a fresh instance per job) | +| **Startup** | Interactive TUI (default `lstk`) | Non-interactive (`docker compose`, `docker run -d`, `lstk --non-interactive`) | + +## Persisting state across runs + +If you tear down the container at the end of a job, nothing is left on disk unless you save it — which is why many teams use a clean instance every time. +When you **do** need to reuse infrastructure or data between pipeline runs or steps, CI is fully supported: + +- **[Cloud Pods](/aws/capabilities/state-management/cloud-pods/)** — save and load snapshots; the [`setup-localstack`](https://github.com/localstack/setup-localstack) action can load and save pods via `state-backend: cloud-pods` (see [GitHub Actions](/aws/integrations/continuous-integration/github-actions/) — _Store Localstack state_). +- **Snapshot-based [persistence](/aws/capabilities/state-management/persistence/)** — enable `PERSISTENCE=1` and mount a volume so state survives container restarts on the same runner or workspace. +- **State export/import** — run `localstack state export` and `localstack state import` and pass the file through your CI provider’s **artifacts**, **cache**, or attached storage (for example, see [GitLab CI](/aws/integrations/continuous-integration/gitlab-ci/) — _Store Localstack state_). + +Choose the approach that fits your runner model: for example, multi-job GitLab pipelines often need explicit state handoff because services do not carry between jobs. + +## More CI integrations + +LocalStack has dedicated integration guides for many CI providers: + +- [GitHub Actions](/aws/integrations/continuous-integration/github-actions/) +- [GitLab CI](/aws/integrations/continuous-integration/gitlab-ci/) +- [CircleCI](/aws/integrations/continuous-integration/circleci/) +- [AWS CodeBuild](/aws/integrations/continuous-integration/codebuild/) +- [Travis CI](/aws/integrations/continuous-integration/travis-ci/) +- [Bitbucket Pipelines](/aws/integrations/continuous-integration/bitbucket/) + +See the full [CI/CD integrations](/aws/integrations/continuous-integration/) section for details. diff --git a/src/content/docs/aws/getting-started/faq.mdx b/src/content/docs/aws/getting-started/faq.mdx index 12128b64..3eded1df 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'; 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 017debdb..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/tooling/). 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..a639c333 --- /dev/null +++ b/src/content/docs/aws/getting-started/index.mdx @@ -0,0 +1,51 @@ +--- +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/capabilities/state-management/cloud-pods/) for state management, [IAM policy enforcement](/aws/capabilities/security-testing/iam-policy-enforcement/), and [Chaos Engineering](/aws/capabilities/chaos-engineering/). + +## Explore by deployment + + + +:::note +**Enterprise K8 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/enterprise/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 1821c7d7..8e792cef 100644 --- a/src/content/docs/aws/getting-started/installation.mdx +++ b/src/content/docs/aws/getting-started/installation.mdx @@ -1,137 +1,87 @@ --- title: Installation -description: Basic installation guide to get started with LocalStack on your local machine. +description: Installation guides for LocalStack CLIs, container engines, and orchestration tools. template: doc sidebar: order: 2 --- import { Code, LinkButton, Tabs, TabItem } from '@astrojs/starlight/components'; -import { LOCALSTACK_VERSION } from "astro:env/server"; +import { LOCALSTACK_VERSION } from 'astro:env/server'; -## LocalStack CLI +LocalStack provides multiple installation paths depending on your development environment and requirements. We recommend using a CLI-based installation for the most consistent local development experience. -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. +Choose the CLI that fits your workflow: use [`lstk`](#lstk) for a streamlined, non-Python setup, or [LocalStack CLI](#localstack-cli) for access to our complete feature set. -### Installing LocalStack CLI +## lstk -The CLI starts and manages the LocalStack Docker container. -For alternative methods of managing the LocalStack container, see our [alternative installation instructions](#alternatives). +`lstk` is a lightweight, Go-based binary that manages the authentication and container lifecycle in a single workflow. - - - - -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: - - +:::caution[Early Release] +`lstk` currently supports core lifecycle commands: `start`, `stop`, `logs`, and `status`. For advanced features like Cloud Pods or Extensions, use the [LocalStack CLI](#localstack-cli). +::: -Then extract the LocalStack CLI from the terminal: +**Install lstk** - - -
-Alternative: Homebrew on Linux + + + ```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`. + + -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: +**Start LocalStack** ```bash -brew install localstack/tap/localstack-cli -``` -
- - - - +lstk start -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: - - +The first execution initiates a browser-based login flow. Subsequent starts use credentials stored in your system keyring. -
- - +## LocalStack CLI -You can download the pre-built binary for your architecture using the link below: +The LocalStack CLI is the primary tool for managing all LocalStack capabilities. -Intel (AMD64) +**Requirement:** You must have a working [Docker installation](https://docs.docker.com/get-docker/) before proceeding. -Then extract the archive and execute the binary in Powershell. - +### Install LocalStack CLI - +x86-64 +ARM64 -If you cannot use the binary releases of LocalStack, you can install the Python distribution. +Extract the binary to `/usr/local/bin`: -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 [release page](https://github.com/localstack/localstack/releases). +brew install localstack/tap/localstack-cli -```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 +python3 -m pip install --upgrade 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. +Do not use `sudo` or the `root` user. Install and execute LocalStack entirely under a local non-root user. ::: - - -### Starting LocalStack + +### Start LocalStack CLI To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal: @@ -139,7 +89,6 @@ To verify that the LocalStack CLI was installed correctly, you can check the ver You are all set! - :::note To start LocalStack, you must first [set up your auth token](/aws/getting-started/auth-token). ::: @@ -156,7 +105,7 @@ localstack start # start localstack in background with -d flag / / / __ \/ ___/ __ `/ /\__ \/ __/ __ `/ ___/ //_/ / /___/ /_/ / /__/ /_/ / /___/ / /_/ /_/ / /__/ ,< /_____/\____/\___/\__,_/_//____/\__/\__,_/\___/_/|_| - + 💻 LocalStack CLI ${LOCALSTACK_VERSION} 👤 Profile: default @@ -167,8 +116,7 @@ localstack start # start localstack in background with -d flag [12:47:15] detaching bootstrap.py:1262 ``` - -### Updating LocalStack CLI +### Update LocalStack CLI The LocalStack CLI allows you to easily update the different components of LocalStack. To check the various options available for updating, run: @@ -196,200 +144,82 @@ Updating the LocalStack CLI using `localstack update localstack-cli` and `locals 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. +## Container & Orchestration Methods -- [Docker-Compose](#docker-compose)\ - Use Docker Compose to configure and start your LocalStack Docker container. +Use these methods for CI pipelines, server environments, or manual container management. -- [Docker](#docker)\ - Use the Docker CLI to manually start the LocalStack Docker container. - -- [Helm](#helm)\ - Use Helm to create a LocalStack deployment in a Kubernetes cluster. - -LocalStack runs inside a Docker container, and the above options are different ways to start and manage the LocalStack Docker container. - -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/capabilities/config/docker-images). - -### LocalStack Desktop +### Docker Compose -Learn more about our desktop client at [LocalStack Desktop](/aws/capabilities/web-app/localstack-desktop) and download it [here](https://app.localstack.cloud/download). +Recommended for CI and team environments. Create a `docker-compose.yml` with the following configuration: -### 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/tooling/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 services: localstack: container_name: "${LOCALSTACK_DOCKER_NAME:-localstack-main}" - image: localstack/localstack-pro # required for Pro + image: localstack/localstack-pro 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:4566:4566" # Gateway + - "127.0.0.1:4510-4559:4510-4559" # External service range environment: - # Activate LocalStack for AWS: https://docs.localstack.cloud/getting-started/auth-token/ - - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} # required for Pro - # LocalStack configuration: https://docs.localstack.cloud/references/configuration/ - - DEBUG=${DEBUG:-0} + - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} - PERSISTENCE=${PERSISTENCE:-0} volumes: - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" - "/var/run/docker.sock:/var/run/docker.sock" -``` - - -Start the container by running the following command: -```bash -docker compose up ``` -:::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. +Execute `docker compose up` to start. -- 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. +### Docker CLI -- 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: +Run the container directly via the Docker engine: ```bash docker run \ --rm -it \ -p 127.0.0.1:4566:4566 \ -p 127.0.0.1:4510-4559:4510-4559 \ - -p 127.0.0.1:443:443 \ - -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ -v /var/run/docker.sock:/var/run/docker.sock \ + -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \ localstack/localstack-pro -``` - -:::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 of LocalStack, use the appropriate tag: `docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack:`. - Check-out the [LocalStack releases](https://github.com/localstack/localstack/releases) 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. -- 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/capabilities/config/configuration). - 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). +``` -- 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: -### Helm +```bash +helm repo add localstack-repo [https://helm.localstack.cloud](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 [Helm](https://helm.sh). +``` -#### Prerequisites +## Graphical User Interfaces (GUIs) -- [Kubernetes](https://kubernetes.io) -- [Helm](https://helm.sh/docs/intro/install/) +### LocalStack Desktop -#### Deploy LocalStack using Helm +Manage local instances via a standalone desktop application. [Download here](https://app.localstack.cloud/download). -You can deploy LocalStack in a Kubernetes cluster by running these commands: -```bash -helm repo add localstack-repo https://helm.localstack.cloud -helm upgrade --install localstack localstack-repo/localstack -``` +### Docker Desktop Extension -The Helm charts are not maintained in the main repository, but in a [separate one](https://github.com/localstack/helm-charts). +Install the [official extension](https://hub.docker.com/extensions/localstack/localstack-docker-desktop) to manage LocalStack directly from the Docker Desktop dashboard. -## What's next? -Now that you have LocalStack up and running, the following resources might be useful for your next steps: -- 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/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/capabilities/config/configuration) such that it perfectly fits your need. -- [Use LocalStack in your CI environment](/aws/integrations/continuous-integration/) to increase your code quality. -- [Checkout LocalStack's Cloud Developer Tools](/aws/tooling/) to further increase your development efficiency with LocalStack. -- Find out about the ways you can [configure LocalStack](/aws/capabilities/config/configuration). ## Troubleshooting #### The LocalStack CLI installation is successful, but I cannot execute `localstack` If you can successfully install LocalStack using `pip` but you cannot use it in your terminal, you most likely haven't set up your operating system's / terminal's `PATH` variable (in order to tell them where to find programs installed via `pip`). + - If you are using Windows, you can enable the `PATH` configuration when installing Python, [as described in the official docs of Python](https://docs.python.org/3/using/windows.html#finding-the-python-executable). - If you are using a MacOS or Linux operating system, please make sure that the `PATH` is correctly set up - either system wide, or in your terminal. As a workaround you can call the LocalStack CLI python module directly: + ```bash python3 -m localstack.cli.main ``` @@ -397,12 +227,15 @@ python3 -m localstack.cli.main #### The `localstack` CLI does not start the LocalStack container If you are using the `localstack` CLI to start LocalStack, but the container is not starting, please check the following: + - Uncheck the **Use kernel networking for UDP** option in Docker Desktop (**Settings** → **Resources** → **Network**) or follow the steps in our [documentation](/aws/tooling/dns-server#system-dns-configuration) to disable it. - Start LocalStack with a specific DNS address: + ```bash DNS_ADDRESS=0 localstack start ``` -- Remove port 53 as indicated in our [standard `docker-compose.yml` file](https://github.com/localstack/localstack/blob/main/docker-compose-pro.yml). + +- Remove port 53 as indicated in our [standard `docker-compose.yml` file](https://github.com/localstack/localstack/blob/main/docker-compose-pro.yml). #### How should I access the LocalStack logs on my local machine? @@ -446,3 +279,8 @@ After running the task, run the diagnostic endpoint and share the archive file w We have extensive network troubleshooting documentation available [here](/aws/capabilities/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 [Local Development Guide](/aws/getting-started/local-development) to start LocalStack and deploy a serverless API. This guide walks you through deploying a Lambda function backed by a DynamoDB table entirely on your local machine. 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..bb8ca588 --- /dev/null +++ b/src/content/docs/aws/getting-started/local-development.mdx @@ -0,0 +1,315 @@ +--- +title: Local Development +description: Deploy a serverless application locally using Lambda and DynamoDB on LocalStack. +template: doc +sidebar: + order: 3 +--- + +import { Tabs, TabItem, Steps } from '@astrojs/starlight/components'; + +## 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: +- **LocalStack Container:** Running the core emulation engine. +- **Serverless API:** A Lambda function with a configured Function URL. +- **Persistence Layer:** A DynamoDB table for message storage. +- **Local Cloud Environment:** A functional AWS-emulated sandbox. + +Select your preferred deployment method to begin: **AWS CLI** or **Terraform**. + +## Prerequisites + +- [Docker](https://docs.docker.com/get-docker/) engine installed and active. +- A [LocalStack account](https://app.localstack.cloud/sign-up). + +## Step 1: Install and Start LocalStack + +The `lstk` CLI provides the fastest initialization path by automating authentication and image management. + + + + Install `lstk`: + + ```bash + brew install localstack/tap/lstk + ``` + + 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](https://app.localstack.cloud) + ``` + + :::note[Early Release] + `lstk` currently supports core lifecycle commands (start, stop, logs, status). For advanced features such as Cloud Pods or Extensions, use the [LocalStack CLI](/aws/getting-started/installation/#localstack-cli). + ::: + + + + If you are using the full-featured LocalStack CLI, ensure you have [configured your auth token](/aws/getting-started/auth-token/) before starting: + + ```bash + localstack start + ``` + + When the container is ready, you'll see these log lines: + + ```bash + __ _______ __ __ + / / ____ _________ _/ / ___// /_____ ______/ /__ + / / / __ \/ ___/ __ `/ /\__ \/ __/ __ `/ ___/ //_/ + / /___/ /_/ / /__/ /_/ / /___/ / /_/ /_/ / /__/ ,< + /_____/\____/\___/\__,_/_//____/\__/\__,_/\___/_/|_| + + 💻 LocalStack CLI ${LOCALSTACK_VERSION} + 👤 Profile: default + + [12:47:13] starting LocalStack in Docker mode 🐳 localstack.py:494 + preparing environment bootstrap.py:1240 + configuring container bootstrap.py:1248 + starting container bootstrap.py:1258 + [12:47:15] detaching bootstrap.py:1262 + ``` + + + + +## Step 2: Deploy serverless API + +Deploy the Lambda function and DynamoDB table using either the `awslocal` or `tflocal` wrappers. These tools automatically route commands to your local instance instead of AWS. + + + + + + 1. Install the `awslocal` wrapper: + + ```bash + pip install awscli-local + ``` + + 2. Create the Lambda function source. + Execute the following to create a project directory 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') + if method == 'POST': + item = {'id': str(uuid.uuid4()), **json.loads(event.get('body', '{}'))} + 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 + ``` + + 3. Create the DynamoDB table: + + ```bash + awslocal dynamodb create-table \ + --table-name Messages \ + --attribute-definitions AttributeName=id,AttributeType=S \ + --key-schema AttributeName=id,KeyType=HASH \ + --billing-mode PAY_PER_REQUEST + ``` + + 4. Deploy the Lambda function: + + ```bash + awslocal 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} + + awslocal lambda wait function-active --function-name messages-api + ``` + + 5. Configure a public URL and retrieve the endpoint: + + ```bash + awslocal lambda create-function-url-config \ + --function-name messages-api \ + --auth-type NONE + + LAMBDA_URL=$(awslocal lambda list-function-url-configs \ + --function-name messages-api \ + --query 'FunctionUrlConfigs[0].FunctionUrl' \ + --output text) + echo $LAMBDA_URL + ``` + + + + + + 1. Install Terraform and the `tflocal` wrapper: + + ```bash + pip install terraform-local + ``` + + 2. Create a `main.tf` file in a new directory: + + ```hcl + 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') + if method == 'POST': + item = {'id': str(uuid.uuid4()), **json.loads(event.get('body', '{}'))} + 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 + } + ``` + + 3. Initialize and apply the configuration: + + ```bash + tflocal init && tflocal apply -auto-approve + ``` + + 4. Retrieve the endpoint: + + ```bash + LAMBDA_URL=$(tflocal output -raw function_url) + echo $LAMBDA_URL + ``` + + + + +## Step 3: Test the API + +Send a POST request to store a message in the 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 +{ "id": "a1b2c3d4-...", "message": "Hello, LocalStack!" } +``` + +Retrieve all your messages: + +```bash +curl "$LAMBDA_URL" + +``` + +The Lambda function executes within the local environment and interacts with the emulated DynamoDB service. Because no actual cloud resources are created, you won't incur any 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 [Resource Browser](https://app.localstack.cloud/inst/default/status) to inspect your Lambda functions and DynamoDB tables in real-time. + +## Step 5: 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 ``` + ```bash localstack stop ``` + +{/* prettier-ignore-end */} + +To persist state across restarts, see [Persistence](/aws/capabilities/state-management/persistence/) or [Cloud Pods](/aws/capabilities/state-management/cloud-pods/). + +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 testing pipelines and GitHub Actions workflows. + 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 7774291f..00000000 --- a/src/content/docs/aws/getting-started/quickstart.mdx +++ /dev/null @@ -1,361 +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 Web Application account](https://app.localstack.cloud/sign-up) & [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/integrations/aws-native-tools/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/integrations/aws-native-tools/aws-cli/#configuring-an-endpoint-url) or a [custom profile](/aws/integrations/aws-native-tools/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/capabilities/state-management/persistence) or learn about [Cloud Pods](/aws/capabilities/state-management/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. -- [Capabilities](/aws/capabilities/): Learn about LocalStack's capabilities including features like IAM policy stream, state management, and more. -- [Tooling](/aws/tooling/): Get details on LocalStack's tooling and integrations. -- [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/styles/global.css b/src/styles/global.css index c00c4feb..33e14b98 100644 --- a/src/styles/global.css +++ b/src/styles/global.css @@ -108,6 +108,30 @@ h3 { transform: translateY(-2px); } +.path-secondary-card { + margin-top: 1rem; +} + +.path-secondary-card .path-secondary-card__title { + font-size: 18px; + font-weight: 500; + letter-spacing: -0.12px; +} + +.path-secondary-card .path-secondary-card__body { + font-size: 16px; + line-height: 26px; + color: var(--sl-color-gray-3); +} + +.path-secondary-card .path-secondary-card__body > :first-child { + margin-top: 0; +} + +.path-secondary-card .path-secondary-card__body > :last-child { + margin-bottom: 0; +} + .service-box-content { height: 100%; display: flex;