diff --git a/src/content/docs/aws/capabilities/cloud-sandbox/ephemeral-instances.md b/src/content/docs/aws/capabilities/cloud-sandbox/ephemeral-instances.md index 6f78205f4..5cb6bd80f 100644 --- a/src/content/docs/aws/capabilities/cloud-sandbox/ephemeral-instances.md +++ b/src/content/docs/aws/capabilities/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/capabilities/security-testing/custom-tls-certificates.mdx b/src/content/docs/aws/capabilities/security-testing/custom-tls-certificates.mdx index 0b070258f..309273172 100644 --- a/src/content/docs/aws/capabilities/security-testing/custom-tls-certificates.mdx +++ b/src/content/docs/aws/capabilities/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/getting-started/installation/#helm)), 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/getting-started/installation/#helm-kubernetes)), 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/capabilities/state-management/cloud-pods.mdx b/src/content/docs/aws/capabilities/state-management/cloud-pods.mdx index 10c52cbad..d96146d20 100644 --- a/src/content/docs/aws/capabilities/state-management/cloud-pods.mdx +++ b/src/content/docs/aws/capabilities/state-management/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 000000000..2427ddbbe --- /dev/null +++ b/src/content/docs/aws/getting-started/ai-workflows.mdx @@ -0,0 +1,43 @@ +--- +title: AI & Agent Workflows +description: Integrate LocalStack with AI coding assistants, MCP servers, and agent-driven infrastructure automation. +template: doc +sidebar: + order: 5 +--- + +LocalStack provides a secure, emulated environment for developing and testing AI-assisted workflows. You can iterate on AI-generated infrastructure code and agentic deployment tasks without incurring cloud costs or risking production AWS environments by using a local cloud sandbox. + +## Capability Map + +| Use Case | Recommended Tooling | +| :--- | :--- | +| **AI Assistant Resource Management** | [LocalStack MCP Server](/aws/tooling/mcp-server/) | +| **Autonomous Infrastructure Deployment** | [LocalStack Skills](https://github.com/localstack/skills) | +| **Local IaC Validation** | LocalStack + `tflocal` / `cdklocal` / `awslocal` | + + +## Model Context Protocol (MCP) Integration + +The LocalStack MCP Server connects compatible AI clients (such as Claude, Cursor, or Windsurf) to your local cloud environment. This integration allows AI agents to manage the full local cloud lifecycle, including container management, resource deployment, and log analysis. + +:::note[Official MCP Documentation] +For detailed configuration instructions, prerequisite checks, and the complete tool reference, read our [LocalStack MCP Server guide](https://docs.localstack.cloud/aws/tooling/mcp-server/). You don't need to start LocalStack manually before using MCP; agents can initialize the container using the management tools provided by the server. +::: + + +## Agent-Driven Automation with Skills + +[LocalStack Skills](https://github.com/localstack/skills) provide pre-defined agent skill definitions for automating AWS architecture deployments. These skills allow agents to scaffold environments, iterate on architecture designs, and manage LocalStack state autonomously. + +Skills implementation scenarios: +- **Rapid Prototyping**: Scaffold new local environments without manual infrastructure coding. +- **Agent-First Development**: Establish LocalStack as a primary deployment target for autonomous agents. +- **Architecture Iteration**: Test complex architectural changes in a risk-free, local sandbox. + +Refer to the [LocalStack Skills repository](https://github.com/localstack/skills) for available skill definitions and setup instructions. + + +## Next steps + +You have explored the integration patterns for AI and agent-driven development. Proceed to the [Auth Token guide](/aws/getting-started/auth-token/) to configure your licensing and unlock advanced LocalStack features. diff --git a/src/content/docs/aws/getting-started/auth-token.mdx b/src/content/docs/aws/getting-started/auth-token.mdx index b71c45a14..a167d95ea 100644 --- a/src/content/docs/aws/getting-started/auth-token.mdx +++ b/src/content/docs/aws/getting-started/auth-token.mdx @@ -1,228 +1,105 @@ --- title: Auth Token -description: Configure your Auth Token to access and activate LocalStack. +description: Configure and manage LocalStack Auth Tokens for local development and CI/CD environments. template: doc sidebar: - order: 3 + order: 6 --- import { Code, Tabs, TabItem } from '@astrojs/starlight/components'; -## Introduction +The Auth Token is a mandatory credential required to pull the `localstack-pro` image and activate service entitlements. It links your local instance to your workspace license and enables access to the full suite of emulated AWS services. -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. +## Token Types -Auth tokens come in two types: a **Developer Auth Token** and a **CI 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. | -- 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. +Manage both token types on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application. -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 registering on the [LocalStack Web Application](https://app.localstack.cloud/sign-up). -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 full access to your license and workspace. **Do not commit tokens to version control.** If a token is exposed, rotate it immediately via the Web Application to invalidate existing sessions. ::: -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 - -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. +## Configuration Methods -:::danger +Authentication requirements vary based on your chosen execution method. -- 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). - ::: +### 1. lstk (Automated) +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. -### LocalStack CLI - -You should set the `LOCALSTACK_AUTH_TOKEN` environment variable either before or during the startup of LocalStack using the `localstack` command-line interface (CLI). +```bash +lstk start - - - \nlocalstack start`} - lang="shell" - /> - - - \nlocalstack start`} - lang="powershell" - /> - - +``` -:::note +### 2. LocalStack CLI -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. - ::: +If you use the standard CLI, set your token using the `auth` command. This persists the credential in your local configuration. -You have the option to run your LocalStack container in the background by appending the `-d` flag to the `localstack start` command. +### 3. Docker & Docker Compose -The `localstack` CLI automatically detects the Auth Token and appropriately conveys it to the LocalStack container. +For direct container execution, inject the token as an environment variable. -:::note -If you are using LocalStack with an Auth Token, it's necessary to download the [LocalStack for AWS image](/aws/capabilities/config/docker-images#localstack-for-aws-image), which includes Pro services and several advanced features. -::: +**Docker CLI:** -### Docker - -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} +```bash docker run \ --rm -it \ - -p 4566:4566 \ - -p 4510-4559:4510-4559 \ - -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:- } \ + -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} \ localstack/localstack-pro -``` - -For more information about starting LocalStack with Docker, take a look at our [Docker installation](/aws/getting-started/installation/#docker) guide. -### Docker Compose - -To start LocalStack using `docker compose`, you have to include the `LOCALSTACK_AUTH_TOKEN` environment variable in your `docker-compose.yml` file: - -```yaml -environment: - - 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/integrations/continuous-integration/). +**Docker Compose:** -## 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. +```yaml +services: + localstack: + image: localstack/localstack-pro + environment: + - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN} -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. +``` -## Licensing configuration & activation checkup +## License Assignment -To avoid logging any licensing-related error messages, set `LOG_LICENSE_ISSUES=0` in your environment. -Refer to our [configuration guide](/aws/capabilities/config/configuration/#localstack-for-aws) for more information. +An Auth Token is only valid if a license is assigned to your user identity or workspace. -The simplest method to verify if LocalStack is active is by querying the health endpoint for a list of running services: +**Assignment Workflow:** - - +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** (Admins receive full permissions by default). +4. Save the configuration to activate the license for that identity. - ```bash - curl http://localhost:4566/_localstack/info | jq - ``` +:::note +An active Auth Token will fail to initialize the container if a valid license has not been assigned to the associated user. +::: - - - ```bash - Invoke-WebRequest -Uri http://localhost:4566/_localstack/info | ConvertFrom-Json - ``` +## Activation Verification - - +Verify the activation status by querying the LocalStack info endpoint: -The following output would be retrieved: +**Successful Activation Output:** -```bash +```json { - "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 -### How do I activate older versions of LocalStack (Before v3.0)? +## Next steps -Prior to the introduction of Auth Tokens, LocalStack used **API keys** managed through the `LOCALSTACK_API_KEY` environment variable for activation. +You have successfully completed the Getting Started sequence! +Proceed to the [FAQ](/aws/getting-started/faq/) for troubleshooting common scenarios, or explore our [supported local AWS services](/aws/services/) to begin building. -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 @@ -273,4 +150,5 @@ 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/). + 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 000000000..fb7ac2f10 --- /dev/null +++ b/src/content/docs/aws/getting-started/ci-cd.mdx @@ -0,0 +1,153 @@ +--- +title: CI/CD Integration +description: implementation guides for LocalStack in automated pipelines, including GitHub Actions, Docker Compose, and state management. +template: doc +sidebar: + order: 4 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +Integrating LocalStack into CI/CD environments enables automated integration testing without cloud infrastructure costs or vendor dependency. CI configurations differ from local development environments in authentication methods and startup workflows. + +Key operational differences in CI/CD include: +- **Authentication**: Use a dedicated CI Auth Token instead of a personal Developer token. +- **Initialization**: Execute LocalStack in non-interactive mode using Docker Compose, the Docker CLI, or specialized CI actions. +- **Isolation**: Initialize a fresh LocalStack instance for each job to ensure reproducible test results. +- **State Management**: Utilize Cloud Pods or state export/import commands to persist infrastructure across pipeline stages. + +## Step 1: Configure CI Auth Token + +Dedicated CI Auth Tokens are required for automated environments to ensure security and auditability. + +1. Navigate to the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application. +2. Generate a new **CI Auth Token**. +3. Store the token as a protected secret within your CI provider (e.g., `LOCALSTACK_AUTH_TOKEN`). + +:::danger[Security Best Practice] +Never commit your auth tokens to source control. +Always inject tokens via your CI provider's secrets or environment variable system. +Rotate compromised tokens immediately via the Web Application. Old tokens are invalidated instantly. +::: + +:::note +Read the [Auth Token guide](/aws/getting-started/auth-token/) for full details on token types and configuration. +::: + +## Step 2: Start LocalStack in CI + +Select the integration method compatible with your CI runner architecture. + + + + Use the official GitHub Action to initialize LocalStack as a workflow step: + + ```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://integration-test-bucket + pytest tests/integration/ + ``` + + + The `setup-localstack` action pulls the image, starts the container, and waits for LocalStack to be ready. + + + + Define LocalStack as a service in your `docker-compose.yml` for containerized environments: + + ```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" + environment: + - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} + volumes: + - "/var/run/docker.sock:/var/run/docker.sock" + ``` + + Start the service and verify readiness before executing tests: + + ```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. + ::: + + + + + Initialize the container directly using the Docker engine: + + ```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 + ``` + + + +## Technical Comparison: Local vs. CI/CD + +| Feature | Local Development | CI/CD Environment | +| :--- | :--- | :--- | +| **Interface** | `lstk` or LocalStack CLI | Docker Compose / `docker run`, or `lstk --non-interactive` | +| **Authentication** | Browser-based or stored credentials | `LOCALSTACK_AUTH_TOKEN` environment variable | +| **Token Type** | Individual Developer Token | Dedicated CI Token | +| **State** | Persistent by choice | Ephemeral (standard) or Snapshotted (Cloud Pods) | +| **Startup Mode** | Interactive (TUI) (default `lstk`) | Non-interactive (Headless) (`docker compose`, `docker run -d`, `lstk --non-interactive`) | + +## State Persistence in CI + +While most pipelines favor ephemeral instances for clean test cycles, certain workflows require persisting infrastructure state across jobs or runners. + +- **[Cloud Pods](/aws/capabilities/state-management/cloud-pods/)**: Save or load snapshots using the `setup-localstack` action with the `state-backend: cloud-pods` configuration. +- **Snapshot Persistence Engine**: Enable `PERSISTENCE=1` and mount a host volume to retain data across container restarts on the same runner. +- **State Export/Import Commands**: Use `localstack state export` and `localstack state import` to pass infrastructure state via CI artifacts or caching mechanisms. + +## Next steps + +You have configured LocalStack for automated environments and explored various CI/CD integration patterns. Proceed to the [AI & Agent Workflows Guide](/aws/getting-started/ai-workflows/) to learn how to integrate LocalStack with AI coding assistants and automate infrastructure tasks. + +## Resources + +- [GitHub Actions Integration](/aws/integrations/continuous-integration/github-actions/): Advanced workflows and configuration options. +- [CircleCI Guide](/aws/integrations/continuous-integration/circleci/): Implementation details for CircleCI environments. +- [GitLab CI Integration](/aws/integrations/continuous-integration/gitlab-ci/): Service-based setup for GitLab runners. +- [AWS CodeBuild](/aws/integrations/continuous-integration/codebuild/): Native AWS CI/CD integration. diff --git a/src/content/docs/aws/getting-started/faq.mdx b/src/content/docs/aws/getting-started/faq.mdx index 12128b64a..3eded1dfc 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 017debdb2..000000000 --- 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 000000000..a639c333b --- /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 1821c7d7d..eed8fd769 100644 --- a/src/content/docs/aws/getting-started/installation.mdx +++ b/src/content/docs/aws/getting-started/installation.mdx @@ -1,24 +1,62 @@ --- 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 + +`lstk` is a lightweight, Go-based binary that manages the authentication and container lifecycle in a single workflow. + +:::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). +::: + +**Install lstk** + + + + ```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`. + + + +**Start LocalStack** + +```bash +lstk start + +``` + +The first execution initiates a browser-based login flow. Subsequent starts use credentials stored in your system keyring. + + +## LocalStack CLI + +The LocalStack CLI is the primary tool for managing all LocalStack capabilities. + +**Requirement:** You must have a working [Docker installation](https://docs.docker.com/get-docker/) before proceeding. + +### Install LocalStack CLI -The CLI starts and manages the LocalStack Docker container. -For alternative methods of managing the LocalStack container, see our [alternative installation instructions](#alternatives). @@ -26,22 +64,43 @@ For alternative methods of managing the LocalStack container, see our [alternati You can download the pre-built binary for your architecture using the link below: -x86-64 -ARM64 + + 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 @@ -51,6 +110,7 @@ If you are using [Homebrew for Linux](https://docs.brew.sh/Homebrew-on-Linux), y ```bash brew install localstack/tap/localstack-cli ``` +
@@ -68,16 +128,28 @@ brew install localstack/tap/localstack-cli You may download the binary for your architecture using the link below: -Intel (AMD64) + + Intel (AMD64) + or use the following curl command: - + Then extract the LocalStack CLI from the terminal: - + @@ -86,9 +158,16 @@ Then extract the LocalStack CLI from the terminal: You can download the pre-built binary for your architecture using the link below: -Intel (AMD64) + + Intel (AMD64) + Then extract the archive and execute the binary in Powershell. + @@ -112,8 +191,8 @@ To download a specific version of LocalStack, replace `` with the requi ```bash python3 -m pip install localstack== ``` -::: +::: :::tip[MacOS Sierra?] If you have problems with permissions in MacOS X Sierra, install with: @@ -121,6 +200,7 @@ If you have problems with permissions in MacOS X Sierra, install with: ```bash python3 -m pip install --user localstack ``` + ::: :::danger @@ -131,7 +211,9 @@ It should be installed and started 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 +221,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 +237,7 @@ localstack start # start localstack in background with -d flag / / / __ \/ ___/ __ `/ /\__ \/ __/ __ `/ ___/ //_/ / /___/ /_/ / /__/ /_/ / /___/ / /_/ /_/ / /__/ ,< /_____/\____/\___/\__,_/_//____/\__/\__,_/\___/_/|_| - + 💻 LocalStack CLI ${LOCALSTACK_VERSION} 👤 Profile: default @@ -167,8 +248,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 +276,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. - -- [Docker-Compose](#docker-compose)\ - Use Docker Compose to configure and start your LocalStack Docker container. - -- [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. +## Container & Orchestration Methods -The LocalStack emulator is available on Docker Hub (`localstack/localstack-pro`). +Use these methods for CI pipelines, server environments, or manual container management. -For a comprehensive overview of the LocalStack images, check out our [Docker images documentation](/aws/capabilities/config/docker-images). +### Docker Compose -### LocalStack Desktop - -Learn more about our desktop client at [LocalStack Desktop](/aws/capabilities/web-app/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/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. +Recommended for CI and team environments. Create a `docker-compose.yml` with the following 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. - -- 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. +Execute `docker compose up` to start. -#### Prerequisites +### Docker CLI -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). +### Helm (Kubernetes) -- To facilitate interoperability, configuration variables can be prefixed with `LOCALSTACK_` in docker. - For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`. +Deploy LocalStack to a Kubernetes cluster: -- To configure an Auth Token, refer to the [Auth Token](/aws/getting-started/auth-token) documentation. -::: - -### 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 +359,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 +411,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 000000000..bb8ca588f --- /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 7774291f2..000000000 --- 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/content/docs/aws/services/ec2.mdx b/src/content/docs/aws/services/ec2.mdx index cf70e9cda..5234b2137 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 dc6e5158a..26b1274dd 100644 --- a/src/content/docs/aws/services/lambda.mdx +++ b/src/content/docs/aws/services/lambda.mdx @@ -578,7 +578,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/content/docs/aws/tooling/aws-replicator.mdx b/src/content/docs/aws/tooling/aws-replicator.mdx index ab6850812..f42c76a1f 100644 --- a/src/content/docs/aws/tooling/aws-replicator.mdx +++ b/src/content/docs/aws/tooling/aws-replicator.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 @@ -74,7 +74,7 @@ Both methods have two steps: 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/tooling/localstack-cli.md b/src/content/docs/aws/tooling/localstack-cli.md index 063f4efb9..ee64c8126 100644 --- a/src/content/docs/aws/tooling/localstack-cli.md +++ b/src/content/docs/aws/tooling/localstack-cli.md @@ -12,7 +12,7 @@ tags: ["Hobby"] 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). +To install the LocalStack CLI, follow the [installation guide](/aws/getting-started/installation/#install-localstack-cli). :::note This documentation was auto-generated from LocalStack CLI version `LocalStack CLI 2026.3.0`.