From d3a9e83ba370eb7e5635e327907d28397d16982c Mon Sep 17 00:00:00 2001 From: HarshCasper Date: Sun, 5 Nov 2023 21:02:37 +0530 Subject: [PATCH] improve extensions index docs --- content/en/user-guide/extensions/_index.md | 20 +++-- .../extensions/getting-started/index.md | 69 ++++++++++++++++++ .../install-extensions.png | Bin .../mailhog.png | Bin .../user-guide/extensions/quickstart/index.md | 65 ----------------- 5 files changed, 81 insertions(+), 73 deletions(-) create mode 100644 content/en/user-guide/extensions/getting-started/index.md rename content/en/user-guide/extensions/{quickstart => getting-started}/install-extensions.png (100%) rename content/en/user-guide/extensions/{quickstart => getting-started}/mailhog.png (100%) delete mode 100644 content/en/user-guide/extensions/quickstart/index.md diff --git a/content/en/user-guide/extensions/_index.md b/content/en/user-guide/extensions/_index.md index 5f2057c065..d8c11a4fb5 100644 --- a/content/en/user-guide/extensions/_index.md +++ b/content/en/user-guide/extensions/_index.md @@ -3,7 +3,7 @@ title: "LocalStack Extensions" linkTitle: "Extensions" weight: 3 description: > - Use the power of LocalStack Extensions to customize and extend your local development experience. + Use LocalStack Extensions to customize and extend your local development experience. cascade: type: docs slug: extensions @@ -12,15 +12,19 @@ slug: extensions {{< figure src="https://user-images.githubusercontent.com/3996682/184503940-c30bfcac-e049-4ee4-b905-207b340111d1.png" >}} LocalStack Extensions allow developers to extend and customize LocalStack. -Extensions are a feature of our paid offering. -To install and use extensions, you need an active LocalStack license. +Extensions are a feature of our paid offering. LocalStack Extensions enable you to start custom services with LocalStack in the same container, while leveraging the existing features in the ecosystem. -Specific LocalStack Extensions are documented [here]({{< ref "user-guide/extensions/official-extensions" >}}) and -can be discovered on our [Extension Library](https://app.localstack.cloud/extensions/library). -Our blogpost about [LocalStack’s Cloudflare Extension](https://localstack.cloud/blog/2023-06-26-develop-your-cloudflare-workers-aws-apps-locally-with-localstack-miniflare/) -showcases LocalStack as a local cloud development platform beyond AWS emulation. +Developers can add new services, extend existing services, and even add custom functionality. The Extensions API allows developers to easily plug in their own custom logic and services into the LocalStack container. + +You can use LocalStack Extensions to: + +- Starting custom services together with LocalStack in the same container (see our [Cloudflare Workers Extension](https://localstack.cloud/blog/2023-06-26-develop-your-cloudflare-workers-aws-apps-locally-with-localstack-miniflare/)). +- Instrumenting AWS requests with additional information before they reach your Lambdas. +- Logging AWS API calls to custom data backends. + +The officially supported [LocalStack Extensions]({{< ref "user-guide/extensions/official-extensions" >}}) can be discovered on our [Extension Library](https://app.localstack.cloud/extensions/library). To install and use extensions, you need an active LocalStack license. {{}} The feature and the API are currently experimental and may be subject to change. -Please report any issues or feature requests on our [GitHub repository](https://github.com/localstack/localstack-extensions). +Please report any issues or feature requests on [LocalStack Extension's GitHub repository](https://github.com/localstack/localstack-extensions). {{}} diff --git a/content/en/user-guide/extensions/getting-started/index.md b/content/en/user-guide/extensions/getting-started/index.md new file mode 100644 index 0000000000..bbe3525684 --- /dev/null +++ b/content/en/user-guide/extensions/getting-started/index.md @@ -0,0 +1,69 @@ +--- +title: "Getting started" +linkTitle: "Getting started" +weight: 3 +description: > + Get started with LocalStack extensions by installing and using the official MailHog extension. +--- + +## Introduction + +MailHog is an open source email testing tool for developers. It provides a simple SMTP server and web interface that allows developers to easily catch and inspect emails sent from their application during development. In this guide, you will install and use the [official MailHog extension for LocalStack](https://github.com/localstack/localstack-extensions/tree/main/mailhog) and send an email through SES, while inspecting it in MailHog. + +## Prerequisites + +- [LocalStack Account](https://app.localstack.cloud/) +- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) + +## Installation + +To get started, start your LocalStack instance with your `LOCALSTACK_API_KEY`. Access our [Extension Manager](https://app.localstack.cloud/inst/default/extensions/manage), and click the **Install** button for the MailHog extension. + +{{< figure src="install-extensions.png" alt="Extensions Manager" title="Extensions Manager" width="800">}} + +You'll receive a confirmation prompt indicating that LocalStack container will restart, after which the extension will become accessible. Check your LocalStack logs for MailHog extension output, where you should see relevant logging information: + +```bash +2023-10-11T19:10:54.708 INFO --- [ MainThread] l.extensions.platform : loaded 1 extensions +2023-10-11T19:10:54.709 INFO --- [ MainThread] mailhog.extension : starting mailhog server +2023-10-11T19:10:54.709 INFO --- [ MainThread] mailhog.extension : configuring SMTP host to internal mailhog smtp: localhost:25 +... +2023-10-11T19:10:55.023 INFO --- [ MainThread] mailhog.extension : serving mailhog extension on host: http://mailhog.localhost.localstack.cloud:4566 +2023-10-11T19:10:55.023 INFO --- [ MainThread] mailhog.extension : serving mailhog extension on path: http://localhost:4566/mailhog/ +``` + +## Usage + +MailHog enables you to conduct end-to-end testing of applications that utilize SES (Simple Email Service) for sending emails. To test this, let's use the AWS CLI to send an email. + +### Send an Email + +You can use the [`VerifyEmailIdentity`](https://docs.aws.amazon.com/cli/latest/reference/ses/verify-email-identity.html) API to verify an email address with SES. This is a required step before you can send emails from SES. Run the following command to verify an email address: + +{{< command >}} +$ aws --endpoint-url=http://localhost:4566 \ + ses verify-email-identity --email-address user1@yourdomain.com +{{< /command >}} + +You can further send an email using the [`SendEmail`](https://docs.aws.amazon.com/cli/latest/reference/ses/send-email.html) API. Run the following command to send an email: + +{{< command >}} +$ aws --endpoint-url=http://localhost:4566 \ + ses send-email \ + --from user1@yourdomain.com \ + --message 'Body={Text={Data="Hello from LocalStack to MailHog"}},Subject={Data=Test Email}' \ + --destination 'ToAddresses=recipient1@example.com' +{{< /command >}} + +### Navigate to Extension UI + +Navigate in your browser to the [MailHog UI in LocalStack](http://mailhog.localhost.localstack.cloud:4566/). You should see the email you sent in the MailHog UI. + +{{< figure src="mailhog.png" alt="Mailhog UI" title="Mailhog UI" width="800">}} + +## Next steps + +- Explore our collection of official extensions, along with a growing ecosystem of third-party extensions, in our [Extensions Library](https://app.localstack.cloud/extensions/library). +- Learn about the various methods for extension management and automating their installation when using LocalStack in a CI environment. Get detailed insights from our [Managing Extensions]({{< ref "managing-extensions" >}}) guide. +- Want to create your own extensions? Dive into our guide on [Developing Extensions]({{< ref "developing-extensions" >}}) for step-by-step instructions. + diff --git a/content/en/user-guide/extensions/quickstart/install-extensions.png b/content/en/user-guide/extensions/getting-started/install-extensions.png similarity index 100% rename from content/en/user-guide/extensions/quickstart/install-extensions.png rename to content/en/user-guide/extensions/getting-started/install-extensions.png diff --git a/content/en/user-guide/extensions/quickstart/mailhog.png b/content/en/user-guide/extensions/getting-started/mailhog.png similarity index 100% rename from content/en/user-guide/extensions/quickstart/mailhog.png rename to content/en/user-guide/extensions/getting-started/mailhog.png diff --git a/content/en/user-guide/extensions/quickstart/index.md b/content/en/user-guide/extensions/quickstart/index.md deleted file mode 100644 index c1f68fbad0..0000000000 --- a/content/en/user-guide/extensions/quickstart/index.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Quickstart" -tags: ["extensions"] -weight: 3 -description: > - Get started with LocalStack extensions ---- - -In this quickstart guide, we will install and use the official [MailHog extensions](https://github.com/localstack/localstack-extensions/tree/main/mailhog). - -## Install an extension - -First, start up your LocalStack instance and navigate to our [Extension Manager App](https://app.localstack.cloud/inst/default/extensions/manage). -Then, click the "Install" button of the MailHog extension: - -{{< figure src="install-extensions.png" >}} - -You will be prompted to confirm that LocalStack will be restarted, and then the extension should become available. -In your LocalStack logs you should see the MailHog extension logging some output: - -``` -2023-10-11T19:10:54.708 INFO --- [ MainThread] l.extensions.platform : loaded 1 extensions -2023-10-11T19:10:54.709 INFO --- [ MainThread] mailhog.extension : starting mailhog server -2023-10-11T19:10:54.709 INFO --- [ MainThread] mailhog.extension : configuring SMTP host to internal mailhog smtp: localhost:25 -... -2023-10-11T19:10:55.023 INFO --- [ MainThread] mailhog.extension : serving mailhog extension on host: http://mailhog.localhost.localstack.cloud:4566 -2023-10-11T19:10:55.023 INFO --- [ MainThread] mailhog.extension : serving mailhog extension on path: http://localhost:4566/mailhog/ -``` - -## Use the extension - -With MailHog, you can perform end-to-end testing of applications that send emails via SES. -Let's use the AWS CLI tool to send an email: - -### Send an Email through SES - -{{< command >}} -aws --endpoint-url=http://localhost:4566 \ - ses verify-email-identity --email-address user1@yourdomain.com -{{< /command >}} - -{{< command >}} -aws --endpoint-url=http://localhost:4566 \ - ses send-email \ - --from user1@yourdomain.com \ - --message 'Body={Text={Data="Hello from LocalStack to MailHog"}},Subject={Data=Test Email}' \ - --destination 'ToAddresses=recipient1@example.com' -{{< /command >}} - -### Open the extension's UI - -Now, navigate in your browser to the MailHog UI in LocalStack: http://mailhog.localhost.localstack.cloud:4566/ - -You should see the email there: - -{{< figure src="mailhog.png" >}} - -## Next steps - -* We have a range of official extensions, and a growing ecosystem of third-party extensions. - Check them out in our [Extensions Library](https://app.localstack.cloud/extensions/library). -* There are different ways of managing extensions, and automating the installation of extensions when using LocalStack in CI. - You can find out more in our [Managing Extensions]({{< ref "managing-extensions" >}}) guide. -* You can also build your own extensions! - Check out our guide on [Developing Extensions]({{< ref "developing-extensions" >}}).