From 6b2fd257e81cdb2405ffd4ac49bfd178be7bd429 Mon Sep 17 00:00:00 2001 From: Daniel Fangl Date: Wed, 6 Oct 2021 15:32:10 +0200 Subject: [PATCH 1/9] add command shortcode and refactor first documents to use it --- assets/scss/_variables_project.scss | 7 +++ content/en/docs/Getting started/_index.md | 43 ++++++++++--------- .../getting-started-pro/index.md | 26 +++++------ .../transparent-execution-mode/dns-server.md | 25 ++++------- layouts/shortcodes/command.html | 10 +++++ 5 files changed, 61 insertions(+), 50 deletions(-) create mode 100644 layouts/shortcodes/command.html diff --git a/assets/scss/_variables_project.scss b/assets/scss/_variables_project.scss index b7d3e1b54b..79ba131869 100644 --- a/assets/scss/_variables_project.scss +++ b/assets/scss/_variables_project.scss @@ -18,5 +18,12 @@ $primary: #30638E !default; margin-top: 1em; } +.command-prefix { + -moz-user-select: none; + -webkit-user-select: none; + -ms-user-select: none; + user-select: none; +} + // workaround for https://github.com/google/docsy/issues/694 @import "/css/shortcodes.css"; diff --git a/content/en/docs/Getting started/_index.md b/content/en/docs/Getting started/_index.md index ca0b95f56a..937600aba5 100644 --- a/content/en/docs/Getting started/_index.md +++ b/content/en/docs/Getting started/_index.md @@ -48,9 +48,9 @@ Please make sure to install the following tools on your machine before moving on #### Installation The easiest way to install the LocalStack CLI is via `pip`: -```sh -python3 -m pip install localstack -``` +{{< command >}} +$ python3 -m pip install localstack +{{< / command >}} {{< alert >}} **Note**: Please do **not** use `sudo` or the `root` user - LocalStack should be installed and started entirely under a local non-root user. @@ -58,7 +58,8 @@ If you have problems with permissions in MacOS X Sierra, install with `python3 - {{< /alert >}} Afterwards you should be able to use the LocalStack CLI in your terminal: -``` + +{{< command >}} $ localstack --help Usage: localstack [OPTIONS] COMMAND [ARGS]... @@ -66,7 +67,7 @@ Usage: localstack [OPTIONS] COMMAND [ARGS]... Options: ... -``` +{{< / command >}} #### Troubleshooting ##### The installation is successful, but I cannot execute `localstack` on my terminal. @@ -75,16 +76,16 @@ If you can successfully install LocalStack using `pip` but you cannot use it in - 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: -```sh -python3 -m localstack.cli.main -``` +{{< command >}} +$ python3 -m localstack.cli.main +{{< / command >}} #### Starting LocalStack with the LocalStack CLI By default, LocalStack is started inside a Docker container by running: -```sh -localstack start -``` +{{< command >}} +$ localstack start +{{< / command >}} {{< alert title="Notes" >}} - This command starts all services provided by LocalStack. @@ -108,9 +109,9 @@ You can check if `docker` is correctly configured on your machine by executing ` #### Starting LocalStack with Docker You can start the Docker container simply by executing the following `docker run` command: -``` -docker run --rm -it -p 4566:4566 -p 4571:4571 localstack/localstack -``` +{{< command >}} +$ docker run --rm -it -p 4566:4566 -p 4571:4571 localstack/localstack +{{< / command >}} {{< alert title="Notes" >}} - This command pulls the current nighty build from the `master` branch (if you don't have the image locally) and **not** the latest supported version. @@ -139,9 +140,9 @@ If you want to manually manage your Docker container, it's usually a good idea t #### Starting LocalStack with Docker-Compose You can use the [`docker-compose.yml` file from the official LocalStack repository](https://github.com/localstack/localstack/blob/master/docker-compose.yml) and use this command (currently requires `docker-compose` version 1.9.0+): -``` -docker-compose up -``` +{{< command >}} +$ docker-compose up +{{< / command >}} {{< alert title="Notes" >}} - This command pulls the current nighty build from the `master` branch (if you don't have the image locally) and **not** the latest supported version. @@ -163,10 +164,10 @@ If you want to deply LocalStack in your [Kubernetes](https://kubernetes.io) clus #### Deploy LocalStack using Helm You can deploy LocalStack in a Kubernetes cluster by running these commands: -```sh -helm repo add localstack-repo https://helm.localstack.cloud -helm upgrade --install localstack localstack-repo/localstack -``` +{{< command >}} +$ helm repo add localstack-repo https://helm.localstack.cloud +$ helm upgrade --install localstack localstack-repo/localstack +{{< / command >}} The Helm charts are not maintained in the main repository, but in a [separate one](https://github.com/localstack/helm-charts). diff --git a/content/en/docs/Getting started/getting-started-pro/index.md b/content/en/docs/Getting started/getting-started-pro/index.md index 8aa93b6d17..3f8ce10982 100644 --- a/content/en/docs/Getting started/getting-started-pro/index.md +++ b/content/en/docs/Getting started/getting-started-pro/index.md @@ -31,16 +31,16 @@ You can find your API key in the [LocalStack Web Interface](https://app.localsta LocalStack Pro expects your API key to be present in the environment variable `LOCALSTACK_API_KEY`. Before starting LocalStack, please define the environment variable in your terminal like this: -```sh +{{< command >}} $ export LOCALSTACK_API_KEY= -``` +{{< / command >}} ### Starting LocalStack Pro using the CLI When starting LocalStack using the LocalStack CLI, you dot not have to perform any further steps (after exporting the environment variable). -```sh +{{< command >}} $ localstack start -``` +{{< / command >}} LocalStack will detect the API key and properly pass it to the LocalStack container. @@ -48,14 +48,14 @@ LocalStack will detect the API key and properly pass it to the LocalStack contai When starting LocalStack using a `docker run` command, you have to specify the API key using the `-e` flag for environment variables like this: -{{< highlight bash "hl_lines=5" >}} -docker run \ +{{< command "hl_lines=5" >}} +$ docker run \ --rm -it \ -p 4566:4566 \ -p 4571:4571 \ -e LOCALSTACK_API_KEY=${LOCALSTACK_API_KEY:- } \ localstack/localstack -{{< / highlight >}} +{{< / command >}} For more information about starting LocalStack, take a look at our general [Getting Started]({{< ref "Getting started" >}}) guide. @@ -79,9 +79,9 @@ If you want to make sure that LocalStack is only started if LocalStack Pro can b The easiest way to check if LocalStack Pro is activated is to check the health endpoing of LocalStack for a list of the running services: -``` -curl localhost:4566/health | jq -``` +{{< command >}} +$ curl localhost:4566/health | jq +{{< / command >}} If a Pro-only [service]({{< ref "Local AWS Services" >}}) -- like [XRay]({{< ref "XRay-Tracing" >}}) -- is running, LocalStack Pro has started successfully. @@ -129,9 +129,9 @@ socket.gaierror: [Errno -3] Temporary failure in name resolution Please confirm this by using a tool like `dig`: -```sh -dig api.localstack.cloud -``` +{{< command >}} +$ dig api.localstack.cloud +{{< / command >}} If the result has some other status than `status: NOERROR`, your machine cannot resolve this domain. diff --git a/content/en/docs/LocalStack Tools/transparent-execution-mode/dns-server.md b/content/en/docs/LocalStack Tools/transparent-execution-mode/dns-server.md index 8addb029d9..3201bf50b5 100644 --- a/content/en/docs/LocalStack Tools/transparent-execution-mode/dns-server.md +++ b/content/en/docs/LocalStack Tools/transparent-execution-mode/dns-server.md @@ -53,17 +53,18 @@ The DNS server can be configured to match your usecase. ## Limitations When you configure transparent execution mode using DNS, you may still have to configure your application's AWS SDK to **accept self-signed certificates**. This is a technical limitation caused by the SSL certificate validation mechanism, due to the fact that we are repointing AWS domain names (e.g., `*.amazonaws.com`) to `localhost`. For example, the following command will fail with an SSL error: -``` +{{< command >}} $ aws kinesis list-streams SSL validation failed for https://kinesis.us-east-1.amazonaws.com/ [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate (_ssl.c:1076) -``` +{{< / command >}} ... whereas the following command works: -``` +{{< command >}} $ PYTHONWARNINGS=ignore aws --no-verify-ssl kinesis list-streams { "StreamNames": [] } -``` +{{< / command >}} + Disabling SSL validation depends on the programming language and version of the AWS SDK used. For example, the [`boto3` AWS SDK for Python](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/core/session.html#boto3.session.Session.client) provides a parameter `verify=False` to disable SSL verification. Similar parameters are available for most other AWS SDKs. ## System DNS configuration @@ -97,14 +98,10 @@ This makes LocalStack bind port 53 on 127.0.0.1, whereas systemd-resolved binds Once LocalStack is started, you can test the DNS server using `dig @127.0.0.1 s3.amazonaws.com` versus `dig @127.0.0.53 s3.amazonaws.com`, the former should return an A record `127.0.0.1`, the latter the real AWS DNS result. * Run: - ```bash - $ localstack dns systemd-resolved - ``` + {{< command >}}$ localstack dns systemd-resolved{{< / command >}} To revert, please run: - ```bash - $ localstack dns systemd-resolved --revert - ``` + {{< command >}}$ localstack dns systemd-resolved --revert{{< / command >}} **Note**: You need sudo privileges to execute this command. @@ -127,14 +124,10 @@ If the interface name is not mentioned, it is usually the first 12 characters of If you use the default bridge network, it is usually `docker0`. 2. Configure the DNS resolver for the bridge network: - ``` - # resolvectl dns - ``` + {{< command >}}# resolvectl dns {{< / command >}} 3. Set the DNS route to route only the above mentioned domain names (and subdomains) to LocalStack: - ``` - # resolvectl domain ~amazonaws.com ~aws.amazon.com ~cloudfront.net ~localhost.localstack.cloud - ``` + {{< command >}}# resolvectl domain ~amazonaws.com ~aws.amazon.com ~cloudfront.net ~localhost.localstack.cloud{{< / command >}} In both cases, you can use `resolvectl query s3.amazonaws.com` or `resolvectl query example.com` to check which interface your DNS request is routed through, to confirm only the above mentioned domains (and its subdomains) are routed to LocalStack. diff --git a/layouts/shortcodes/command.html b/layouts/shortcodes/command.html new file mode 100644 index 0000000000..5598681359 --- /dev/null +++ b/layouts/shortcodes/command.html @@ -0,0 +1,10 @@ +{{/* Command shortcode. Current limitations: will interpret comments as root command (# prefixes will not be selectable, use ## if this is necessary)*/}} + +{{ $inner := trim .Inner "\n" }} +{{ $inner = replaceRE `(?m)^\s*((?:\$|#)\s)` "###CUSTOM_PREFIX###$1###CUSTOM_PREFIX_END###" $inner}} +{{ $options := "" }} +{{ with .Get 0 }} +{{ $options = . }} +{{ end }} +{{ $highlighted := highlight $inner "text" $options }} +{{- replaceRE `###CUSTOM_PREFIX###((?:\$|#)\s)###CUSTOM_PREFIX_END###` "$1" $highlighted | safeHTML -}} From b498c0a58f87dc80d4b448b37e4897d0a5c9d873 Mon Sep 17 00:00:00 2001 From: Daniel Fangl Date: Wed, 6 Oct 2021 15:58:48 +0200 Subject: [PATCH 2/9] change more commands to new shortcode --- .../en/docs/Integrations/architect/index.md | 18 ++++----- content/en/docs/Integrations/aws-cli/index.md | 39 ++++++++++--------- content/en/docs/Integrations/pulumi/index.md | 34 ++++++++-------- .../serverless-framework/index.md | 18 ++++----- .../en/docs/Integrations/terraform/index.md | 18 ++++----- .../Local AWS Services/apigatewayv2/index.md | 4 +- .../docs/Local AWS Services/appsync/index.md | 6 +-- .../docs/Local AWS Services/athena/index.md | 5 ++- .../Local AWS Services/cloudfront/index.md | 17 ++++---- .../Local AWS Services/elasticsearch/index.md | 18 ++++----- 10 files changed, 90 insertions(+), 87 deletions(-) diff --git a/content/en/docs/Integrations/architect/index.md b/content/en/docs/Integrations/architect/index.md index a5161a2bde..829ed55286 100644 --- a/content/en/docs/Integrations/architect/index.md +++ b/content/en/docs/Integrations/architect/index.md @@ -25,15 +25,15 @@ The ``` arclocal``` command has the same usage as the ```arc``` command, so you Create a test directory -```bash -mkdir architect_quickstart && cd architect_quickstart -``` +{{< command >}} +$ mkdir architect_quickstart && cd architect_quickstart +{{< / command >}} then create an architect project -``` -arclocal init -``` +{{< command >}} +$ arclocal init +{{< / command >}} ### Deployment @@ -43,9 +43,9 @@ Now you need to start LocalStack. The services you need to start are - cloudformation After LocalStack has started you can deploy your Architect setup via -``` -arclocal deploy -``` +{{< command >}} +$ arclocal deploy +{{< / command >}} ## Further reading diff --git a/content/en/docs/Integrations/aws-cli/index.md b/content/en/docs/Integrations/aws-cli/index.md index cb533efa0f..0e3fdbc4eb 100644 --- a/content/en/docs/Integrations/aws-cli/index.md +++ b/content/en/docs/Integrations/aws-cli/index.md @@ -68,14 +68,14 @@ The source code can be found on GitHub: https://github.com/localstack/awscli-loc You can install the `awslocal` command via `pip`: -``` -pip install awscli-local[ver1] -``` +{{< command >}} +$ pip install awscli-local[ver1] +{{< / command >}} Note that the command above also installs the latest version of the underlying AWS CLI version 1 (`awscli`) package. Use this command if you prefer to manage your own version of `awscli` (e.g., `v1`/`v2`) and install the wrapper script only: -``` -pip install awscli-local -``` +{{< command >}} +$ pip install awscli-local +{{< / command >}} {{< alert >}} **Note:** Automatic installation of AWS CLI version 2 is currently not supported yet (at the time of writing there is no official pypi package for `v2` available), but the `awslocal` technically also works with AWS CLI v2 (see [this section]({{< ref "#limitations" >}}) for more details). @@ -107,11 +107,11 @@ To work around this issue, you have 2 options: We do not recommend this, but it is technically possible. Also, you should install these libraries in a Python virtualenv, to avoid version clashes with other libraries on your system: -```bash -virtualenv .venv -. .venv/bin/activate -pip install https://github.com/boto/botocore/archive/v2.zip https://github.com/aws/aws-cli/archive/v2.zip -``` +{{< command >}} +$ virtualenv .venv +$ . .venv/bin/activate +$ pip install https://github.com/boto/botocore/archive/v2.zip https://github.com/aws/aws-cli/archive/v2.zip +{{< / command >}} ## AWS CLI v2 @@ -123,10 +123,11 @@ By default, the container running [amazon/aws-cli](https://docs.aws.amazon.com/c To ensure that the two docker containers can communicate create a network on the docker engine: -```bash +{{< command >}} $ docker network create localstack 0c9cb3d37b0ea1bfeb6b77ade0ce5525e33c7929d69f49c3e5ed0af457bdf123 -``` +{{< / command >}} + Then modify the `docker-compose.yml` specifying the network to use: ```yaml @@ -138,24 +139,24 @@ networks: Run AWS Cli v2 docker container using this network (example): -```bash +{{< command >}} $ docker run --network localstack --rm -it amazon/aws-cli --endpoint-url=http://localstack:4566 lambda list-functions { "Functions": [] } -``` +{{< / command >}} If you use AWS CLI v2 from a docker container often, create an alias: -```bash +{{< command >}} $ alias laws='docker run --network localstack --rm -it amazon/aws-cli --endpoint-url=http://localstack:4566' -``` +{{< / command >}} So you can type: -```bash +{{< command >}} $ laws lambda list-functions { "Functions": [] } -``` +{{< / command >}} diff --git a/content/en/docs/Integrations/pulumi/index.md b/content/en/docs/Integrations/pulumi/index.md index cc5e1c98c7..5b5d98c499 100644 --- a/content/en/docs/Integrations/pulumi/index.md +++ b/content/en/docs/Integrations/pulumi/index.md @@ -143,15 +143,15 @@ Make sure your LocalStack is running. For the example stack, the only required service is S3. After updating the stack configuration, and starting localstack, you can run: -```bash -pulumi up -``` +{{< command >}} +$ pulumi up +{{< / command >}} once the stack update was performed, you can run: -```bash -awslocal s3 ls -``` +{{< command >}} +$ awslocal s3 ls +{{< / command >}} Where you should see something like @@ -169,16 +169,16 @@ You can find the source code repository here: https://github.com/localstack/pulu `pulumilocal` requires that you already have the `pulumi` command in your path. Then, simply run -```bash -pip install pulumi-local -``` +{{< command >}} +$ pip install pulumi-local +{{< / command >}} then, -``` +{{< command >}} pulumi version pulumilocal version -``` +{{< / command >}} should output the same value. @@ -186,17 +186,17 @@ should output the same value. Instead of manually editing a stack configuration as explained earlier, you can run -```bash -pulumilocal init -``` +{{< command >}} +$ pulumilocal init +{{< / command >}} which will create a `Pulumi.localstack.yaml` stack configuration, and initialize an additional stack named `localstack`. You can now run -```bash -pulumilocal up -``` +{{< command >}} +$ pulumilocal up +{{< / command >}} to start the localstack stack. diff --git a/content/en/docs/Integrations/serverless-framework/index.md b/content/en/docs/Integrations/serverless-framework/index.md index 1891d58639..611598a1a1 100644 --- a/content/en/docs/Integrations/serverless-framework/index.md +++ b/content/en/docs/Integrations/serverless-framework/index.md @@ -68,9 +68,9 @@ resources: ## Install and configure Serverless-LocalStack Plugin To install the plugin, execute the following command in the root of your project. -```bash -npm install -D serverless-localstack -``` +{{< command >}} +$ npm install -D serverless-localstack +{{< / command >}} Next, set up the plugin by adding the following properties to `serverless.yml`. ```yaml @@ -126,14 +126,14 @@ else: You can now deploy your Serverless service to LocalStack. First, start LocalStack by running -```bash -localstack start -``` +{{< command >}} +$ localstack start +{{< / command >}} Then deploy the endpoint by running -```bash -serverless deploy --stage local -``` +{{< command >}} +$ serverless deploy --stage local +{{< / command >}} The expected result should be similar to: diff --git a/content/en/docs/Integrations/terraform/index.md b/content/en/docs/Integrations/terraform/index.md index 4fd42b39f4..e67fbf7d3d 100644 --- a/content/en/docs/Integrations/terraform/index.md +++ b/content/en/docs/Integrations/terraform/index.md @@ -23,9 +23,9 @@ Apart from some information Terraform expects there are basically only two thing Before we start changing the configuration, create and change into a new directory for this sample -```bash -mkdir terraform_quickstart && cd terraform_quickstart -``` +{{< command >}} +$ mkdir terraform_quickstart && cd terraform_quickstart +{{< / command >}} Inside this directory, create a file called `main.tf`. The following changes go into this file. @@ -115,14 +115,14 @@ After starting LocalStack you can now deploy the s3 bucket via `terraform` and i All you need to do is to initialize Terraform -```bash -terraform init -``` +{{< command >}} +$ terraform init +{{< / command >}} and then deploy the configuration -```bash -terraform deploy -``` +{{< command >}} +$ terraform deploy +{{< / command >}} ## Endpoint configuration diff --git a/content/en/docs/Local AWS Services/apigatewayv2/index.md b/content/en/docs/Local AWS Services/apigatewayv2/index.md index 6badf1d826..6a0e53c5a8 100644 --- a/content/en/docs/Local AWS Services/apigatewayv2/index.md +++ b/content/en/docs/Local AWS Services/apigatewayv2/index.md @@ -23,7 +23,7 @@ functions: Upon deployment of the Serverless project, a new API Gateway V2 endpoint will be created in LocalStack. The [`awslocal`](https://github.com/localstack/awscli-local) CLI can be used to get the list of APIs, which should contain the WebSocket endpoint, e.g., `ws://localhost:4510` in the example below: -```bash +{{< command >}} $ awslocal apigatewayv2 get-apis { "Items": [{ @@ -32,7 +32,7 @@ $ awslocal apigatewayv2 get-apis ... }] } -``` +{{< / command >}} Assuming your project contains a simple Lambda `handler.js` like this: diff --git a/content/en/docs/Local AWS Services/appsync/index.md b/content/en/docs/Local AWS Services/appsync/index.md index f05dad3d5b..939e9c5ced 100644 --- a/content/en/docs/Local AWS Services/appsync/index.md +++ b/content/en/docs/Local AWS Services/appsync/index.md @@ -40,8 +40,8 @@ $util.toJson($context.result["Items"]) ``` Once things have been wired up properly, and assuming the ID of your GraphQL API is `"api123"`, you should be able to run the following GraphQL query to retrieve all items from the `"posts"` DynamoDB table: -```bash -curl -d '{"query":"query {getPosts{id{S}}}"}' http://localhost:4605/graphql/api123 -``` +{{< command >}} +$ curl -d '{"query":"query {getPosts{id{S}}}"}' http://localhost:4605/graphql/api123 +{{< / command >}} For more details, please refer to the self-contained sample published in [this Github repository](https://github.com/localstack/localstack-pro-samples/tree/master/appsync-graphql-api). diff --git a/content/en/docs/Local AWS Services/athena/index.md b/content/en/docs/Local AWS Services/athena/index.md index cc16c0b10f..396a3207f3 100644 --- a/content/en/docs/Local AWS Services/athena/index.md +++ b/content/en/docs/Local AWS Services/athena/index.md @@ -8,7 +8,8 @@ description: > LocalStack Pro ships with built-in support for [Athena](https://aws.amazon.com/athena), Amazon's serverless data warehouse and analytics platform. Athena uses [Presto](https://prestodb.github.io/) under the covers, and your Athena instance will be automatically configured with a Hive metastore that connects seamlessly to the LocalStack S3 API. That is, you can easily connect your local S3 buckets and query data directly from S3 via the powerful Athena query API. The following commands illustrate how to use Athena from the command line (assuming you have [`awslocal`](https://github.com/localstack/awscli-local) installed): -```bash + +{{< command >}} $ awslocal athena start-query-execution --query-string 'SELECT 1, 2, 3' { "QueryExecutionId": "c9f453ad" @@ -33,7 +34,7 @@ $ awslocal athena get-query-results --query-execution-id c9f453ad }, "UpdateCount": 0 } -``` +{{< / command >}} {{< alert >}}**Note**: In order to use the Athena API, some additional dependencies have to be fetched from the network, including a Docker image of apprx. 1.5GB which includes Presto, Hive and other tools. These dependencies are automatically fetched when you start up the service, so please make sure you're on a decent internet connection when pulling the dependencies for the first time. diff --git a/content/en/docs/Local AWS Services/cloudfront/index.md b/content/en/docs/Local AWS Services/cloudfront/index.md index 18b7ac309e..765581de3a 100644 --- a/content/en/docs/Local AWS Services/cloudfront/index.md +++ b/content/en/docs/Local AWS Services/cloudfront/index.md @@ -9,14 +9,15 @@ description: > LocalStack Pro supports creation of local CloudFront distributions, which allows you to transparently access your applications and file artifacts via CloudFront URLs like `https://abc123.cloudfront.net`. For example, take the following simple example which creates an S3 bucket, puts a small text file `hello.txt` to the bucket, and then creates a CloudFront distribution which makes the file accessible via a `https://abc123.cloudfront.net/hello.txt` proxy URL (where `abc123` is a placeholder for the real distribution ID): -```bash -awslocal s3 mb s3://bucket1 -echo 'Hello World' > /tmp/hello.txt -awslocal s3 cp /tmp/hello.txt s3://bucket1/hello.txt --acl public-read -domain=$(awslocal cloudfront create-distribution \ - --origin-domain-name bucket1.s3.amazonaws.com | jq -r '.Distribution.DomainName') -curl -k https://$domain/hello.txt -``` + +{{< command >}} +$ awslocal s3 mb s3://bucket1 +$ echo 'Hello World' > /tmp/hello.txt +$ awslocal s3 cp /tmp/hello.txt s3://bucket1/hello.txt --acl public-read +$ domain=$(awslocal cloudfront create-distribution \ + --origin-domain-name bucket1.s3.amazonaws.com | jq -r '.Distribution.DomainName') +$ curl -k https://$domain/hello.txt +{{< / command >}} {{< alert >}} **Note:** In order for CloudFront to be fully functional, your local DNS setup needs to be properly configured. See the section on [configuring the local DNS server]({{< ref "#configuring-local-dns-server" >}}) for details. diff --git a/content/en/docs/Local AWS Services/elasticsearch/index.md b/content/en/docs/Local AWS Services/elasticsearch/index.md index e438654593..92467165b5 100644 --- a/content/en/docs/Local AWS Services/elasticsearch/index.md +++ b/content/en/docs/Local AWS Services/elasticsearch/index.md @@ -22,7 +22,7 @@ You can go ahead and use [awslocal]({{< ref "aws-cli.md#localstack-aws-cli-awslo **Note**: The default Elasticsearch version used is 7.7. {{< /alert >}} -```bash +{{< command >}} $ awslocal es create-elasticsearch-domain --domain-name foobar { "DomainStatus": { @@ -53,7 +53,7 @@ $ awslocal es create-elasticsearch-domain --domain-name foobar } } } -``` +{{< / command >}} In the LocalStack log you will see something like @@ -77,10 +77,10 @@ In the LocalStack log you will see something like and after some time, you should see that the `Created` state of the domain is set to `true`: -```bash +{{< command >}} $ awslocal es describe-elasticsearch-domain --domain-name foobar | jq ".DomainStatus.Created" true -``` +{{< / command >}} ## Interact with the cluster @@ -93,7 +93,7 @@ Additional domains share the same Elasticsearch cluster. For example: -```bash +{{< command >}} $ curl http://localhost:4571 { "name" : "om", @@ -112,12 +112,12 @@ $ curl http://localhost:4571 }, "tagline" : "You Know, for Search" } -``` +{{< / command >}} Or the health endpoint: -```bash -curl -s http://localhost:4571/_cluster/health | jq . +{{< command >}} +$ curl -s http://localhost:4571/_cluster/health | jq . { "cluster_name": "elasticsearch", "status": "green", @@ -135,4 +135,4 @@ curl -s http://localhost:4571/_cluster/health | jq . "task_max_waiting_in_queue_millis": 0, "active_shards_percent_as_number": 100 } -``` +{{< / command >}} From 14b386e20756af0f0798287adea886566cdc334c Mon Sep 17 00:00:00 2001 From: Daniel Fangl Date: Wed, 6 Oct 2021 17:23:12 +0200 Subject: [PATCH 3/9] format more commands to the shortcode --- content/en/docs/Local AWS Services/kinesis/index.md | 4 ++-- content/en/docs/Local AWS Services/s3/index.md | 4 ++-- content/en/docs/Local AWS Services/sqs/index.md | 5 ++--- content/en/docs/Understanding LocalStack/configuration.md | 6 +++--- layouts/shortcodes/command.html | 2 +- 5 files changed, 10 insertions(+), 11 deletions(-) diff --git a/content/en/docs/Local AWS Services/kinesis/index.md b/content/en/docs/Local AWS Services/kinesis/index.md index 26e1959574..888f37e1e6 100644 --- a/content/en/docs/Local AWS Services/kinesis/index.md +++ b/content/en/docs/Local AWS Services/kinesis/index.md @@ -13,7 +13,7 @@ Kinesis is shipped with the LocalStack Community version and is [extensively sup Trying to run the example applications from the [official AWS developer guide](https://docs.aws.amazon.com/streams/latest/dev/examples.html) against LocalStack is a great place to start. Assuming you have `awslocal` installed you can also try out the following commands: -```bash +{{< command >}} $ awslocal kinesis create-stream --stream-name samplestream --shard-count $ awslocal kinesis list-streams @@ -29,7 +29,7 @@ $ awslocal kinesis put-record --cli-binary-format raw-in-base64-out --stream-nam "SequenceNumber": "49622467803485029265018102167378141645049970239670845458", "EncryptionType": "NONE" } -``` +{{< / command >}} ## Kinesis backend providers diff --git a/content/en/docs/Local AWS Services/s3/index.md b/content/en/docs/Local AWS Services/s3/index.md index ca393d0823..16b047d441 100644 --- a/content/en/docs/Local AWS Services/s3/index.md +++ b/content/en/docs/Local AWS Services/s3/index.md @@ -12,7 +12,7 @@ S3 is shipped with the LocalStack Community version and is [extensively supporte Assuming you have [`awslocal`]({{< ref "aws-cli" >}}) installed you can also try the following commands: -```bash +{{< command >}} $ awslocal s3api create-bucket --bucket sample-bucket { @@ -38,7 +38,7 @@ $ awslocal s3api put-object --bucket sample-bucket --key index.html --body index { "ETag": "\"d41d8cd98f00b204e9800998ecf8427e\"" } -``` +{{< / command >}} When working with the `SERVICES` environment variable, please make sure to include `s3` in the list of services. For instance, to load the S3, SQS, and Kinesis service you'd pass the variable as `SERVICES=s3,sqs,kinesis`. diff --git a/content/en/docs/Local AWS Services/sqs/index.md b/content/en/docs/Local AWS Services/sqs/index.md index c8a4ff12a7..2dfeb5be6c 100644 --- a/content/en/docs/Local AWS Services/sqs/index.md +++ b/content/en/docs/Local AWS Services/sqs/index.md @@ -12,7 +12,7 @@ Trying to run the examples in the [official AWS developer](https://docs.aws.amaz Assuming you have [`awslocal`]({{< ref "aws-cli" >}}) installed you can also try the following commands: -```bash +{{< command >}} $ awslocal sqs create-queue --queue-name sample-queue { "QueueUrl": "http://localhost:4566/000000000000/sample-queue" @@ -26,12 +26,11 @@ $ awslocal sqs list-queues } $ awslocal sqs send-message --queue-url http://localhost:4566/00000000000/sample-queue --message-body test - { "MD5OfMessageBody": "098f6bcd4621d373cade4e832627b4f6", "MessageId": "74861aab-05f8-0a75-ae20-74d109b7a76e" } -``` +{{< / command >}} When working with the `SERVICES` environment variable, please make sure to include `sqs` in the list of services. For instance, to load the DynamoDB, SQS, and Kinesis service you'd pass the variable as `SERVICES=dynamodb,sqs,kinesis`. diff --git a/content/en/docs/Understanding LocalStack/configuration.md b/content/en/docs/Understanding LocalStack/configuration.md index 324a132d9b..5363b18262 100644 --- a/content/en/docs/Understanding LocalStack/configuration.md +++ b/content/en/docs/Understanding LocalStack/configuration.md @@ -8,9 +8,9 @@ description: > LocalStack allows for many different configuration options. You can pass these via environment variables, e.g., like the following: -```bash -SERVICES=kinesis,lambda,sqs,dynamodb DEBUG=1 localstack start -``` +{{< command >}} +$ SERVICES=kinesis,lambda,sqs,dynamodb DEBUG=1 localstack start +{{< / command >}} ## Core diff --git a/layouts/shortcodes/command.html b/layouts/shortcodes/command.html index 5598681359..57c2f2dac0 100644 --- a/layouts/shortcodes/command.html +++ b/layouts/shortcodes/command.html @@ -1,7 +1,7 @@ {{/* Command shortcode. Current limitations: will interpret comments as root command (# prefixes will not be selectable, use ## if this is necessary)*/}} {{ $inner := trim .Inner "\n" }} -{{ $inner = replaceRE `(?m)^\s*((?:\$|#)\s)` "###CUSTOM_PREFIX###$1###CUSTOM_PREFIX_END###" $inner}} +{{ $inner = replaceRE `(?m)^ *((?:\$|#) )` "###CUSTOM_PREFIX###$1###CUSTOM_PREFIX_END###" $inner}} {{ $options := "" }} {{ with .Get 0 }} {{ $options = . }} From a5984243e63dd96b85203f166549eb1622db2511 Mon Sep 17 00:00:00 2001 From: Daniel Fangl Date: Wed, 6 Oct 2021 18:07:53 +0200 Subject: [PATCH 4/9] fix the last of the commands --- content/en/docs/Integrations/aws-cli/index.md | 33 ++++++----- content/en/docs/Integrations/pulumi/index.md | 8 +-- .../spring-cloud-function/index.md | 12 ++-- .../elastic-container-registry/index.md | 10 ++-- .../elastic-kubernetes-service/index.md | 4 +- .../elastic-mapreduce/index.md | 4 +- .../Local AWS Services/elasticache/index.md | 8 +-- .../en/docs/Local AWS Services/glue/index.md | 28 +++++----- .../en/docs/Local AWS Services/iam/index.md | 4 +- .../en/docs/Local AWS Services/iot/index.md | 4 +- .../multi-account-setups/index.md | 12 ++-- .../en/docs/Local AWS Services/rds/index.md | 4 +- .../docs/Local AWS Services/route53/index.md | 4 +- .../en/docs/Local AWS Services/ses/index.md | 4 +- .../Lambda Tools/debugging.md.bak | 6 +- .../Lambda Tools/hot-swapping/index.md | 56 +++++++++---------- .../docs/LocalStack Tools/cloud-pods/index.md | 6 +- .../transparent-execution-mode/dns-server.md | 2 +- layouts/shortcodes/command.html | 2 +- 19 files changed, 105 insertions(+), 106 deletions(-) diff --git a/content/en/docs/Integrations/aws-cli/index.md b/content/en/docs/Integrations/aws-cli/index.md index 0e3fdbc4eb..413c61cb39 100644 --- a/content/en/docs/Integrations/aws-cli/index.md +++ b/content/en/docs/Integrations/aws-cli/index.md @@ -13,38 +13,37 @@ All CLI commands that access [services that are implemented in LocalStack]({{< r There are two ways to use the CLI: * Use our `awslocal` drop-in replacement: - ``` - awslocal kinesis list-streams - ``` + {{< command >}} + $ awslocal kinesis list-streams + {{< / command >}} * Configure AWS test environment variables and add the `--endpoint-url=` flag to your `aws` CLI invocations. For example: - ``` - export AWS_ACCESS_KEY_ID="test" - export AWS_SECRET_ACCESS_KEY="test" - export AWS_DEFAULT_REGION="us-east-1" + {{< command >}} + $ export AWS_ACCESS_KEY_ID="test" + $ export AWS_SECRET_ACCESS_KEY="test" + $ export AWS_DEFAULT_REGION="us-east-1" - aws --endpoint-url=http://localhost:4566 kinesis list-streams - ``` + $ aws --endpoint-url=http://localhost:4566 kinesis list-streams + {{< / command >}} ## AWS CLI Use the below command to install `aws`, if not installed already. -``` -pip install awscli -``` +{{< command >}} +$ pip install awscli +{{< / command >}} ### Setting up local region and credentials to run LocalStack aws requires the region and the credentials to be set in order to run the aws commands. Create the default configuration and the credentials. Below key will ask for the Access key id, secret Access Key, region & output format. +Config & credential file will be created under ~/.aws folder -``` -aws configure --profile default - -# Config & credential file will be created under ~/.aws folder -``` +{{< command >}} +$ aws configure --profile default +{{< / command >}} {{< alert >}} **Note** Please use `test` as value for AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to make pre-signed URLs for S3 buckets work. diff --git a/content/en/docs/Integrations/pulumi/index.md b/content/en/docs/Integrations/pulumi/index.md index 5b5d98c499..a00cf151aa 100644 --- a/content/en/docs/Integrations/pulumi/index.md +++ b/content/en/docs/Integrations/pulumi/index.md @@ -22,10 +22,10 @@ This guide follows the instructions from Pulumi's [Get Started with Pulumi and A First, run the following commands and follow the instructions in the CLI to create a new project. -``` -mkdir quickstart && cd quickstart -pulumi new aws-typescript -``` +{{< command >}} +$ mkdir quickstart && cd quickstart +$ pulumi new aws-typescript +{{< / command >}} We use the default configuration values: diff --git a/content/en/docs/Integrations/spring-cloud-function/index.md b/content/en/docs/Integrations/spring-cloud-function/index.md index 452fc8e210..ed72825de8 100644 --- a/content/en/docs/Integrations/spring-cloud-function/index.md +++ b/content/en/docs/Integrations/spring-cloud-function/index.md @@ -79,16 +79,16 @@ install the Gradle build tool on your machine. Then run the following command to initialize a new Gradle project -```shell -gradle init -``` +{{< command >}} +$ gradle init +{{< / command >}} After initialization, you will find the Gradle wrapper script `gradlew`. From now on, we will use the wrapper instead of the globally installed Gradle binary: -``` -./gradlew -``` +{{< command >}} +$ ./gradlew +{{< / command >}} ### Project Settings diff --git a/content/en/docs/Local AWS Services/elastic-container-registry/index.md b/content/en/docs/Local AWS Services/elastic-container-registry/index.md index b3a3694cf9..1b5b6da429 100644 --- a/content/en/docs/Local AWS Services/elastic-container-registry/index.md +++ b/content/en/docs/Local AWS Services/elastic-container-registry/index.md @@ -8,8 +8,8 @@ description: > A basic version of Elastic Container Registry (ECR) is available to store application images. ECR is often used in combination with other APIs that deploy containerized apps, like ECS or EKS. -``` -$ awslocal ecr create-repository --repository-name repo1 +{{< command >}} +$ $ awslocal ecr create-repository --repository-name repo1 { "repository": { "repositoryArn": "arn:aws:ecr:us-east-1:000000000000:repository/repo1", @@ -18,10 +18,10 @@ $ awslocal ecr create-repository --repository-name repo1 "repositoryUri": "localhost:4510/repo1" } } -``` +{{< / command >}} You can then build and tag a new Docker image, and push it to the repository URL (`localhost:4510/repo1` in the example above): -``` +{{< command >}} $ cat Dockerfile FROM nginx ENV foo=bar @@ -36,4 +36,4 @@ fe08d5d042ab: Pushed f2cb0ecef392: Pushed latest: digest: sha256:4dd893a43df24c8f779a5ab343b7ef172fb147c69ed5e1278d95b97fe0f584a5 size: 948 ... -``` +{{< / command >}} diff --git a/content/en/docs/Local AWS Services/elastic-kubernetes-service/index.md b/content/en/docs/Local AWS Services/elastic-kubernetes-service/index.md index 0956da7022..d269ab1043 100644 --- a/content/en/docs/Local AWS Services/elastic-kubernetes-service/index.md +++ b/content/en/docs/Local AWS Services/elastic-kubernetes-service/index.md @@ -12,7 +12,7 @@ Please note that EKS requires an existing local Kubernetes installation. In rece ![Kubernetes in Docker](kubernetes.png) The example below illustrates how to create an EKS cluster configuration (assuming you have [`awslocal`](https://github.com/localstack/awscli-local) installed): -``` +{{< command >}} $ awslocal eks create-cluster --name cluster1 --role-arn r1 --resources-vpc-config '{}' { "cluster": { @@ -30,5 +30,5 @@ $ awslocal eks list-clusters "cluster1" ] } -``` +{{< / command >}} Simply configure your Kubernetes client (e.g., `kubectl` or other SDK) to point to the `endpoint` specified in the `create-cluster` output above. Depending on whether you're calling the Kubernetes API from the local machine or from within a Lambda, you may have to use different endpoint URLs (`https://localhost:6443` vs `https://172.17.0.1:6443`). diff --git a/content/en/docs/Local AWS Services/elastic-mapreduce/index.md b/content/en/docs/Local AWS Services/elastic-mapreduce/index.md index 0b00012e1d..185243ff40 100644 --- a/content/en/docs/Local AWS Services/elastic-mapreduce/index.md +++ b/content/en/docs/Local AWS Services/elastic-mapreduce/index.md @@ -9,12 +9,12 @@ description: > LocalStack Pro allows running data analytics workloads locally via the [EMR](https://aws.amazon.com/emr) API. EMR utilizes various tools in the [Hadoop](https://hadoop.apache.org/) and [Spark](https://spark.apache.org) ecosystem, and your EMR instance is automatically configured to connect seamlessly to the LocalStack S3 API. To create a virtual EMR cluster locally from the command line (assuming you have [`awslocal`](https://github.com/localstack/awscli-local) installed): -``` +{{< command >}} $ awslocal emr create-cluster --release-label emr-5.9.0 --instance-groups InstanceGroupType=MASTER,InstanceCount=1,InstanceType=m4.large InstanceGroupType=CORE,InstanceCount=1,InstanceType=m4.large { "ClusterId": "j-A2KF3EKLAOWRI" } -``` +{{< / command >}} The commmand above will spin up one more more Docker containers on your local machine that can be used to run analytics workloads using Spark, Hadoop, Pig, and other tools. diff --git a/content/en/docs/Local AWS Services/elasticache/index.md b/content/en/docs/Local AWS Services/elasticache/index.md index 6a345028f9..1551e9cec9 100644 --- a/content/en/docs/Local AWS Services/elasticache/index.md +++ b/content/en/docs/Local AWS Services/elasticache/index.md @@ -9,7 +9,7 @@ description: > A basic version of [ElastiCache](https://aws.amazon.com/elasticache/) is provided. By default, the API is started on http://localhost:4598 and supports running a local Redis instance (Memcached support coming soon). After starting LocalStack Pro, you can test the following commands: -``` +{{< command >}} $ awslocal elasticache create-cache-cluster --cache-cluster-id i1 { "CacheCluster": { @@ -20,14 +20,14 @@ $ awslocal elasticache create-cache-cluster --cache-cluster-id i1 } } } -``` +{{< / command >}} Then use the returned port number (`4530`) to connect to the Redis instance: -``` +{{< command >}} $ redis-cli -p 4530 ping PONG $ redis-cli -p 4530 set foo bar OK $ redis-cli -p 4530 get foo "bar" -``` +{{< / command >}} diff --git a/content/en/docs/Local AWS Services/glue/index.md b/content/en/docs/Local AWS Services/glue/index.md index bbc3cf88f0..751f28f3a5 100644 --- a/content/en/docs/Local AWS Services/glue/index.md +++ b/content/en/docs/Local AWS Services/glue/index.md @@ -15,7 +15,7 @@ In order to run Glue jobs, some additional dependencies have to be fetched from ## Creating Databases and Table Metadata The commands below illustrate the creation of some very basic entries (databases, tables) in the Glue data catalog: -``` +{{< command >}} $ awslocal glue create-database --database-input '{"Name":"db1"}' $ awslocal glue create-table --database db1 --table-input '{"Name":"table1"}' $ awslocal glue get-tables --database db1 @@ -27,30 +27,30 @@ $ awslocal glue get-tables --database db1 } ] } -``` +{{< / command >}} ## Running Scripts with Scala and PySpark Assuming we would like to deploy a simple PySpark script `job.py` in the local folder, we can first copy the script to an S3 bucket: -``` +{{< command >}} $ awslocal s3 mb s3://glue-test $ awslocal s3 cp job.py s3://glue-test/job.py -``` +{{< / command >}} Next, we can create a job definition: -``` +{{< command >}} $ awslocal glue create-job --name job1 --role r1 \ --command '{"Name": "pythonshell", "ScriptLocation": "s3://glue-test/job.py"}' -``` +{{< / command >}} ... and finally start the job: -``` +{{< command >}} $ awslocal glue start-job-run --job-name job1 { "JobRunId": "733b76d0" } -``` +{{< / command >}} The returned `JobRunId` can be used to query the status job the job execution, until it becomes `SUCCEEDED`: -``` +{{< command >}} $ awslocal glue get-job-run --job-name job1 --run-id 733b76d0 { "JobRun": { @@ -59,7 +59,7 @@ $ awslocal glue get-job-run --job-name job1 --run-id 733b76d0 "JobRunState": "SUCCEEDED" } } -``` +{{< / command >}} For a more detailed example illustrating how to run a local Glue PySpark job, please refer to this [sample repository](https://github.com/localstack/localstack-pro-samples/tree/master/glue-etl-jobs). @@ -75,12 +75,12 @@ CREATE EXTERNAL TABLE db2.table2 (a1 Date, a2 STRING, a3 INT) LOCATION 's3://tes ``` Then this command will import these DB/table definitions into the Glue data catalog: -``` +{{< command >}} $ awslocal glue import-catalog-to-glue -``` +{{< / command >}} ... and finally they will be available in Glue: -``` +{{< command >}} $ awslocal glue get-databases { "DatabaseList": [ @@ -112,7 +112,7 @@ $ awslocal glue get-tables --database-name db2 } ] } -``` +{{< / command >}} ## Further Reading diff --git a/content/en/docs/Local AWS Services/iam/index.md b/content/en/docs/Local AWS Services/iam/index.md index df3897aaf7..6d5d9999b1 100644 --- a/content/en/docs/Local AWS Services/iam/index.md +++ b/content/en/docs/Local AWS Services/iam/index.md @@ -14,7 +14,7 @@ The environment configuration `ENFORCE_IAM=1` is required to enable this feature {{< /alert >}} Below is a simple example that illustrates the use of IAM policy enforcement. It first attempts to create an S3 bucket with the default user (which fails), then create a user and attempts to create a bucket with that user (which fails again), and then finally attaches a policy to the user to allow `s3:CreateBucket`, which allows the bucket to be created. -``` +{{< command >}} $ awslocal s3 mb s3://test make_bucket failed: s3://test An error occurred (AccessDeniedException) when calling the CreateBucket operation: Access to the specified resource is denied $ awslocal iam create-user --user-name test @@ -32,7 +32,7 @@ $ awslocal iam create-policy --policy-name p1 --policy-document '{"Version":"201 $ awslocal iam attach-user-policy --user-name test --policy-arn arn:aws:iam::000000000000:policy/p1 $ awslocal s3 mb s3://test make_bucket: test -``` +{{< / command >}} ### Supported APIs diff --git a/content/en/docs/Local AWS Services/iot/index.md b/content/en/docs/Local AWS Services/iot/index.md index 6280e9cef6..87005df767 100644 --- a/content/en/docs/Local AWS Services/iot/index.md +++ b/content/en/docs/Local AWS Services/iot/index.md @@ -9,12 +9,12 @@ description: > Basic support for [IoT](https://aws.amazon.com/iot/) (including IoT Analytics, IoT Data, and related APIs) is provided in the Pro version. The main endpoints for creating and updating entities are currently implemented, as well as the CloudFormation integrations for creating them. The IoT API ships with a built-in MQTT message broker. In order to get the MQTT endpoint, the `describe-endpoint` API can be used; for example, using [`awslocal`](https://github.com/localstack/awscli-local): -``` +{{< command >}} $ awslocal iot describe-endpoint { "endpointAddress": "localhost:4520" } -``` +{{< / command >}} This endpoint can then be used with any MQTT client to send/receive messages (e.g., using the endpoint URL `mqtt://localhost:4520`). diff --git a/content/en/docs/Local AWS Services/multi-account-setups/index.md b/content/en/docs/Local AWS Services/multi-account-setups/index.md index c252944827..61bf0cd16f 100644 --- a/content/en/docs/Local AWS Services/multi-account-setups/index.md +++ b/content/en/docs/Local AWS Services/multi-account-setups/index.md @@ -9,12 +9,12 @@ description: > Unlike the open source LocalStack, which uses a single hardcoded account ID (`000000000000`), the Pro version allows to use multiple instances for different AWS account IDs in parallel. In order to set up a multi-account environment, simply configure the `TEST_AWS_ACCOUNT_ID` to include a comma-separated list of account IDs. For example, use the following to start up LocalStack with two account IDs: -``` +{{< command >}} $ TEST_AWS_ACCOUNT_ID=000000000001,000000000002 SERVICES=s3 localstack start -``` +{{< / command >}} You can then use `AWS_ACCESS_KEY_ID` to address resources in the two separate account instances: -``` +{{< command >}} $ AWS_ACCESS_KEY_ID=000000000001 aws --endpoint-url=http://localhost:4566 s3 mb s3://bucket-account-one make_bucket: bucket-account-one $ AWS_ACCESS_KEY_ID=000000000002 aws --endpoint-url=http://localhost:4566 s3 mb s3://bucket-account-two @@ -23,13 +23,13 @@ $ AWS_ACCESS_KEY_ID=000000000001 aws --endpoint-url=http://localhost:4566 s3 ls 2020-05-24 17:09:41 bucket-account-one $ AWS_ACCESS_KEY_ID=000000000002 aws --endpoint-url=http://localhost:4566 s3 ls 2020-05-24 17:09:53 bucket-account-two -``` +{{< / command >}} Note that using an invalid account ID should result in a 404 (not found) error response from the API: -``` +{{< command >}} $ AWS_ACCESS_KEY_ID=123000000123 aws --endpoint-url=http://localhost:4566 s3 ls An error occurred (404) when calling the ListBuckets operation: Not Found -``` +{{< / command >}} {{< alert >}} **Note:** For now, the account ID is encoded directly in the `AWS_ACCESS_KEY_ID` client-side variable, for simplicity. In a future version, we will support proper access key IDs issued by the local IAM service, which will then internally be translated to corresponding account IDs. diff --git a/content/en/docs/Local AWS Services/rds/index.md b/content/en/docs/Local AWS Services/rds/index.md index adf32a0682..323b19bc7b 100644 --- a/content/en/docs/Local AWS Services/rds/index.md +++ b/content/en/docs/Local AWS Services/rds/index.md @@ -9,7 +9,7 @@ description: > LocalStack supports a basic version of [RDS](https://aws.amazon.com/rds/) for testing. Currently, it is possible to spin up PostgreSQL databases on the local machine; support for MySQL and other DB engines is under development and coming soon. The local RDS service also supports the [RDS Data API](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html), which allows executing data queries over a JSON/REST interface. Below is a simple example that illustrates (1) creation of an RDS database, (2) creation of a SecretsManager secret with the DB password, and (3) running a simple `SELECT 123` query via the RDS Data API. -``` +{{< command >}} $ awslocal rds create-db-instance --db-instance-identifier db1 --db-instance-class c1 --engine postgres ... $ awslocal secretsmanager create-secret --name dbpass --secret-string test @@ -28,4 +28,4 @@ $ awslocal rds-data execute-statement --database test --resource-arn arn:aws:rds { "doubleValue": 123 } ]] } -``` +{{< / command >}} diff --git a/content/en/docs/Local AWS Services/route53/index.md b/content/en/docs/Local AWS Services/route53/index.md index 057da76c17..c76ea0a058 100644 --- a/content/en/docs/Local AWS Services/route53/index.md +++ b/content/en/docs/Local AWS Services/route53/index.md @@ -9,14 +9,14 @@ description: > The Route53 API in LocalStack Pro allows you to create hosted zones and to manage DNS entries (e.g., A records) which can then be queried via the built-in DNS server. The example below illustrates the creation of a hosted zone `example.com`, registration of an A record named `test.example.com` that points to `1.2.3.4`, and finally querying the DNS record by using the `dig` command against the DNS server running on `localhost` (inside the LocalStack container, on port `53`): -``` +{{< command >}} $ zone_id=$(awslocal route53 create-hosted-zone --name example.com --caller-reference r1 | jq -r '.HostedZone.Id') $ awslocal route53 change-resource-record-sets --hosted-zone-id $zone_id --change-batch 'Changes=[{Action=CREATE,ResourceRecordSet={Name=test.example.com,Type=A,ResourceRecords=[{Value=1.2.3.4}]}}]' $ dig @localhost test.example.com ... ;; ANSWER SECTION: test.example.com. 300 IN A 1.2.3.4 -``` +{{< / command >}} {{< alert >}} **Note**: Using the built-in DNS capabilities requires privileged access for the LocalStack container (please also refer to the `DNS_ADDRESS` configuration variable). diff --git a/content/en/docs/Local AWS Services/ses/index.md b/content/en/docs/Local AWS Services/ses/index.md index de1bf36f49..e372653600 100644 --- a/content/en/docs/Local AWS Services/ses/index.md +++ b/content/en/docs/Local AWS Services/ses/index.md @@ -11,9 +11,9 @@ The Pro version ships with extended support Simple Email Service (SES), includin Please refer to the [Configuration section]({{< ref "#configuration" >}}) for instructions on how to configure the connection parameters of your SMTP server (`SMTP_HOST`/`SMTP_USER`/`SMTP_PASS`). Once your SMTP server has been configured, you can use the SES user interface in the Web app to create a new email account (e.g., `user1@yourdomain.com`), and then send an email via the command line (or your SES client SDK): -``` +{{< command >}} $ awslocal ses send-email --from user1@yourdomain.com --message 'Body={Text={Data="Lorem ipsum dolor sit amet, consectetur adipiscing elit, ..."}},Subject={Data=Test Email}' --destination 'ToAddresses=recipient1@example.com' -``` +{{< / command >}} The [Web user interface](https://app.localstack.cloud) then allows you to interactively browse through the sent email messages, as illustrated in the screenshot below: diff --git a/content/en/docs/LocalStack Tools/Lambda Tools/debugging.md.bak b/content/en/docs/LocalStack Tools/Lambda Tools/debugging.md.bak index f51e938781..f52d1dd8ff 100644 --- a/content/en/docs/LocalStack Tools/Lambda Tools/debugging.md.bak +++ b/content/en/docs/LocalStack Tools/Lambda Tools/debugging.md.bak @@ -42,9 +42,9 @@ services: Open the `Run/Debug Configurations` window and create a new `Shell Script` with the following content: -```shell -while [[ -z $(docker ps | grep :5050) ]]; do sleep 1; done -``` +{{< command >}} +$ while [[ -z $(docker ps | grep :5050) ]]; do sleep 1; done +{{< / command >}} ![Run/Debug Configurations](../img-inteliji-debugger-1.png) diff --git a/content/en/docs/LocalStack Tools/Lambda Tools/hot-swapping/index.md b/content/en/docs/LocalStack Tools/Lambda Tools/hot-swapping/index.md index 26bc6cd766..8fa8c95703 100644 --- a/content/en/docs/LocalStack Tools/Lambda Tools/hot-swapping/index.md +++ b/content/en/docs/LocalStack Tools/Lambda Tools/hot-swapping/index.md @@ -49,9 +49,9 @@ First, create a watchman wrapper by using [one of our examples](https://github.com/localstack/localstack-pro-samples/tree/master/spring-cloud-function-microservice/bin/watchman.sh) Don't forget to adjust permissions: -```shell -chmod +x bin/watchman.sh -``` +{{< command >}} +$ chmod +x bin/watchman.sh +{{< / command >}} Now configure your build tool to unzip the FatJar to some folder, which will be then mounted to LocalStack. We are using `Gradle` build tool to unpack the @@ -68,9 +68,9 @@ buildHot.dependsOn shadowJar Now run the following command to start watching your project in a hot-swapping mode: -```shell -bin/watchman.sh src "./gradlew buildHot" -``` +{{< command >}} +$ bin/watchman.sh src "./gradlew buildHot" +{{< / command >}} Please note that you still need to configure your deployment tool to use local code mounting. Read the "[Deployment Configuration Examples](#deployment-configuration-examples)" @@ -83,19 +83,19 @@ We will show you how you can do this with a simple example function, taken direc You can check out that code, or use your own lambda functions to follow along. To use the example just do: -```sh -cd /tmp -git clone git@github.com:awsdocs/aws-doc-sdk-examples.git -``` +{{< command >}} +$ cd /tmp +$ git clone git@github.com:awsdocs/aws-doc-sdk-examples.git +{{< / command >}} #### Starting up LocalStack First, we need to make sure we start LocalStack with the right configuration. This is as simple as setting `LAMBDA_REMOTE_DOCKER`(see the [Configuration Documentation]({{< ref "configuration#lambda" >}}) for more information): -```sh -LAMBDA_REMOTE_DOCKER=0 localstack start -``` +{{< command >}} +$ LAMBDA_REMOTE_DOCKER=0 localstack start +{{< / command >}} Accordingly, if you are launching LocalStack via Docker or Docker Compose: @@ -119,21 +119,21 @@ To create the Lambda function, you just need to take care of two things: So, using the AWS example, this would be: -```sh -awslocal lambda create-function --function-name my-cool-local-function \ +{{< command >}} +$ awslocal lambda create-function --function-name my-cool-local-function \ --code S3Bucket="__local__",S3Key="/tmp/aws-doc-sdk-examples/python/example_code/lambda/boto_client_examples" \ --handler lambda_handler_basic.lambda_handler \ --runtime python3.8 \ --role cool-stacklifter -``` +{{< / command >}} You can also check out some of our "[Deployment Configuration Examples](#deployment-configuration-examples)". We can also quickly make sure that it works by invoking it with a simple payload: -```sh -awslocal lambda invoke --function-name my-cool-local-function --payload '{"action": "square", "number": 3}' output.txt -``` +{{< command >}} +$ awslocal lambda invoke --function-name my-cool-local-function --payload '{"action": "square", "number": 3}' output.txt +{{< / command >}} The invocation returns itself returns: @@ -232,9 +232,9 @@ custom: Pass `LAMBDA_MOUNT_CWD` env var with path to the built code directory (in our case to the folder with unzipped FatJar): -```shell -LAMBDA_MOUNT_CWD=$(pwd)/build/hot serverless deploy --stage local -``` +{{< command >}} +$ LAMBDA_MOUNT_CWD=$(pwd)/build/hot serverless deploy --stage local +{{< / command >}} ### AWS Cloud Development Kit (CDK) Configuration @@ -283,11 +283,11 @@ class ApplicationStack(parent: Construct, name: String) : Stack(parent, name) { Then to bootstrap and deploy the stack run the following shell script -```shell -STAGE=local && LAMBDA_MOUNT_CWD=$(pwd)/build/hot && +{{< command >}} +$ STAGE=local && LAMBDA_MOUNT_CWD=$(pwd)/build/hot && cdklocal bootstrap aws://000000000000/$(AWS_REGION) && \ cdklocal deploy -``` +{{< / command >}} ### Terraform Configuration @@ -369,10 +369,10 @@ resource "aws_lambda_function" "exampleFunctionOne" { } ``` -```shell -terraform init && \ +{{< command >}} +$ terraform init && \ terraform apply -var "STAGE=local" -var "LAMBDA_MOUNT_CWD=$(pwd)/build/hot" -``` +{{< / command >}} ## Useful Links diff --git a/content/en/docs/LocalStack Tools/cloud-pods/index.md b/content/en/docs/LocalStack Tools/cloud-pods/index.md index 566d9792fd..905913b7c3 100644 --- a/content/en/docs/LocalStack Tools/cloud-pods/index.md +++ b/content/en/docs/LocalStack Tools/cloud-pods/index.md @@ -12,7 +12,7 @@ You can create and manage Local Cloud Pods via the Web UI, and in order to load Below is a simple example of how you can push and pull Local Cloud Pods using the `localstack` CLI: -```sh +```bash # User 1 pushes state of Cloud Pod to persistent server $ awslocal kinesis list-streams {"StreamNames": ["mystream123"]} @@ -37,7 +37,7 @@ You can use the [LocalStack Web UI](https://app.localstack.cloud/pods) to create ![Local Cloud Pods UI](cloudPodsUI.png) Once the pod has been created, can use the CLI to log in and list the pod in your terminal: -``` +{{< command >}} $ export LOCALSTACK_API_KEY=... $ localstack login ... @@ -45,7 +45,7 @@ $ localstack pod list Name Backend URL Size State ------ --------- --------------------------------- ------ ------- pod1 git ssh://git@github.com/your_org/... 1.68MB Shared -``` +{{< / command >}} {{% alert title="LocalStack Pro feature" color="info" %}} Cloud Pods are a feature of LocalStack Pro. diff --git a/content/en/docs/LocalStack Tools/transparent-execution-mode/dns-server.md b/content/en/docs/LocalStack Tools/transparent-execution-mode/dns-server.md index 3201bf50b5..c319fb7177 100644 --- a/content/en/docs/LocalStack Tools/transparent-execution-mode/dns-server.md +++ b/content/en/docs/LocalStack Tools/transparent-execution-mode/dns-server.md @@ -44,7 +44,7 @@ The DNS server can be configured to match your usecase. * There is the possibility to manually set the DNS server all not-redirected queries will be forwarded to: - ``` + ```bash DNS_SERVER=1.1.1.1 ``` diff --git a/layouts/shortcodes/command.html b/layouts/shortcodes/command.html index 57c2f2dac0..97fd364dcb 100644 --- a/layouts/shortcodes/command.html +++ b/layouts/shortcodes/command.html @@ -1,6 +1,6 @@ {{/* Command shortcode. Current limitations: will interpret comments as root command (# prefixes will not be selectable, use ## if this is necessary)*/}} -{{ $inner := trim .Inner "\n" }} +{{ $inner := trim .Inner "\n " }} {{ $inner = replaceRE `(?m)^ *((?:\$|#) )` "###CUSTOM_PREFIX###$1###CUSTOM_PREFIX_END###" $inner}} {{ $options := "" }} {{ with .Get 0 }} From 1a2cf3291ec1769c5ed84bde3a10e18954afa9e9 Mon Sep 17 00:00:00 2001 From: Daniel Fangl Date: Wed, 6 Oct 2021 18:09:14 +0200 Subject: [PATCH 5/9] add python code type --- .../transparent-execution-mode/patched-sdks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/LocalStack Tools/transparent-execution-mode/patched-sdks.md b/content/en/docs/LocalStack Tools/transparent-execution-mode/patched-sdks.md index 6b38f7c978..7344b70798 100644 --- a/content/en/docs/LocalStack Tools/transparent-execution-mode/patched-sdks.md +++ b/content/en/docs/LocalStack Tools/transparent-execution-mode/patched-sdks.md @@ -11,7 +11,7 @@ The Lambda runtime in LocalStack uses patched AWS SDKs, which are configured to This behavior is enabled by default for most Lambda runtimes when using LocalStack Pro. Assuming you had a Python Lambda handler that attempts to list all S3 buckets. In the past, you had to manually configure the `endpoint_url` parameter on the boto3 client (and potentially use environment switches for dev/prod in your test code): -``` +```python import boto3 def handler(event, context): client = boto3.client("s3", endpoint_url="http://localhost:4566") @@ -19,7 +19,7 @@ def handler(event, context): ``` With the patched AWS SDKs, it now becomes possible to deploy your unmodified production code to LocalStack, simply creating a boto3 client with default settings. The invocations of the boto3 client will be automatically forwarded to the local APIs: -``` +```python import boto3 def handler(event, context): client = boto3.client("s3") From 024c0c23b2a0abab49f594b2ac40dac83b5276ef Mon Sep 17 00:00:00 2001 From: Alexander Rashed Date: Thu, 7 Oct 2021 08:46:47 +0200 Subject: [PATCH 6/9] reafactor code fences to use proper language or command shortcode --- .../en/docs/Integrations/architect/index.md | 11 +- content/en/docs/Integrations/pulumi/index.md | 6 +- .../spring-cloud-function/index.md | 2 +- .../en/docs/Integrations/terraform/index.md | 12 +- .../docs/Local AWS Services/cognito/index.md | 54 +++++---- .../Local AWS Services/elasticsearch/index.md | 1 - .../en/docs/Local AWS Services/glue/index.md | 2 +- .../Lambda Tools/debugging.md.bak | 114 ------------------ .../Lambda Tools/debugging/index.md | 18 +-- .../patched-sdks.md | 4 +- .../Understanding LocalStack/limitations.md | 2 +- 11 files changed, 57 insertions(+), 169 deletions(-) delete mode 100644 content/en/docs/LocalStack Tools/Lambda Tools/debugging.md.bak diff --git a/content/en/docs/Integrations/architect/index.md b/content/en/docs/Integrations/architect/index.md index 829ed55286..072fd513cc 100644 --- a/content/en/docs/Integrations/architect/index.md +++ b/content/en/docs/Integrations/architect/index.md @@ -17,11 +17,12 @@ If you are adapting an existing configuration, you might be able to skip certain ## Example ### Setup -To use Architect in conjunction with Localstack, simply install the ```arclocal``` command (sources can be found [here](https://github.com/localstack/architect-local)). -``` -npm install -g architect-local @architect/architect aws-sdk -``` -The ``` arclocal``` command has the same usage as the ```arc``` command, so you can start right away. +To use Architect in conjunction with Localstack, simply install the `arclocal` command (sources can be found [here](https://github.com/localstack/architect-local)). +{{< command >}} +$ npm install -g architect-local @architect/architect aws-sdk +{{< /command >}} + +The `arclocal` command has the same usage as the `arc` command, so you can start right away. Create a test directory diff --git a/content/en/docs/Integrations/pulumi/index.md b/content/en/docs/Integrations/pulumi/index.md index a00cf151aa..ca97cefe0f 100644 --- a/content/en/docs/Integrations/pulumi/index.md +++ b/content/en/docs/Integrations/pulumi/index.md @@ -52,8 +52,8 @@ Installing dependencies... This will create the following directory structure. -```language - % tree -L 1 +{{< command >}} +$ tree -L 1 . ├── index.ts ├── node_modules @@ -62,7 +62,7 @@ This will create the following directory structure. ├── Pulumi.dev.yaml ├── Pulumi.yaml └── tsconfig.json -``` +{{< / command >}} Now edit your stack configuration `Pulumi.dev.yaml` as follows: diff --git a/content/en/docs/Integrations/spring-cloud-function/index.md b/content/en/docs/Integrations/spring-cloud-function/index.md index ed72825de8..7aaee5ffe3 100644 --- a/content/en/docs/Integrations/spring-cloud-function/index.md +++ b/content/en/docs/Integrations/spring-cloud-function/index.md @@ -245,7 +245,7 @@ Let's configure it to lookup our function Beans by HTTP method and path, create new `application.properties` file under `src/main/resources/application.properties` with the following content: -```properties +```env spring.main.banner-mode=off spring.cloud.function.definition=functionRouter spring.cloud.function.routing-expression=headers['httpMethod'].concat(' ').concat(headers['path']) diff --git a/content/en/docs/Integrations/terraform/index.md b/content/en/docs/Integrations/terraform/index.md index e67fbf7d3d..64d91759cd 100644 --- a/content/en/docs/Integrations/terraform/index.md +++ b/content/en/docs/Integrations/terraform/index.md @@ -34,7 +34,7 @@ The following changes go into this file. First, we have to specify mock credentials for the AWS provider: -``` +```hcl provider "aws" { access_key = "test" @@ -48,7 +48,7 @@ provider "aws" { Second, we need to avoid issues with routing and authentication (as we do not need it). Therefore we need to supply some general parameters: -``` +```hcl provider "aws" { access_key = "test" @@ -66,7 +66,7 @@ provider "aws" { Additionally, we have to point the individual services to LocalStack. In case of S3, this looks like the following snippet -``` +```hcl endpoints { s3 = "http://localhost:4566" } @@ -79,7 +79,7 @@ In case of S3, this looks like the following snippet ### S3 Bucket Now we are adding a minimal s3 bucket outside the provider -``` +```hcl resource "aws_s3_bucket" "test-bucket" { bucket = "my-bucket" } @@ -89,7 +89,7 @@ resource "aws_s3_bucket" "test-bucket" { ### Final Configuration The final (minimal) configuration to deploy an s3 bucket thus looks like this -``` +```hcl provider "aws" { access_key = "mock_access_key" @@ -128,7 +128,7 @@ $ terraform deploy Here is a configuration example with additional endpoints: -``` +```hcl provider "aws" { access_key = "test" secret_key = "test" diff --git a/content/en/docs/Local AWS Services/cognito/index.md b/content/en/docs/Local AWS Services/cognito/index.md index ed9f69ec06..c3b3d2ca08 100644 --- a/content/en/docs/Local AWS Services/cognito/index.md +++ b/content/en/docs/Local AWS Services/cognito/index.md @@ -17,7 +17,7 @@ LocalStack Pro contains basic support for authentication via Cognito. You can cr {{< /alert >}} First, start up LocalStack. In addition to the normal setup, we need to pass several SMTP settings as environment variables. -``` +```env SMTP_HOST= SMTP_USER= SMTP_PASS= @@ -28,12 +28,12 @@ Don't forget to pass Cognito as a service as well. ## Creating a User Pool Just as with aws, you can create a User Pool in LocalStack via -``` -awslocal cognito-idp create-user-pool --pool-name test -``` +{{< command >}} +$ awslocal cognito-idp create-user-pool --pool-name test +{{< /command >}} The response should look similar to this -``` +```json "UserPool": { "Id": "us-east-1_fd924693e9b04f549f989283123a29c2", "Name": "test", @@ -60,28 +60,31 @@ The response should look similar to this "AllowAdminCreateUserOnly": false }, "Arn": "arn:aws:cognito-idp:us-east-1:000000000000:userpool/us-east-1_fd924693e9b04f549f989283123a29c2" +} ``` -We will need the pool-id for further operations, so save it in a ```pool_id``` variable. +We will need the pool-id for further operations, so save it in a `pool_id` variable. Alternatively, you can also use a JSON processor like [jq](https://stedolan.github.io/jq/) to directly extract the necessary information when creating a pool. -``` -pool_id=$(awslocal cognito-idp create-user-pool --pool-name test | jq -rc ".UserPool.Id") -``` + +{{< command >}} +$ pool_id=$(awslocal cognito-idp create-user-pool --pool-name test | jq -rc ".UserPool.Id") +{{< /command >}} + ## Adding a Client Now we add a client to our newly created pool. We will also need the ID of the created client for the next step. The complete command for client creation with subsequent ID extraction is therefore -``` -client_id=$(awslocal cognito-idp create-user-pool-client --user-pool-id $pool_id --client-name test-client | jq -rc ".UserPoolClient.ClientId") -``` +{{< command >}} +$ client_id=$(awslocal cognito-idp create-user-pool-client --user-pool-id $pool_id --client-name test-client | jq -rc ".UserPoolClient.ClientId") +{{< /command >}} ## Signing up and confirming a user With these steps already taken, we can now sign up a user. -``` -awslocal cognito-idp sign-up --client-id $client_id --username example_user --password 12345678 --user-attributes Name=email,Value= -``` +{{< command >}} +$ awslocal cognito-idp sign-up --client-id $client_id --username example_user --password 12345678 --user-attributes Name=email,Value= +{{< /command >}} The response should look similar to this -``` +```json { "UserConfirmed": false, "UserSub": "5fdbe1d5-7901-4fee-9d1d-518103789c94" @@ -91,17 +94,17 @@ and you should have received a new e-mail! As you can see, our user is still unconfirmed. We can change this with the following instruction. -``` -awslocal cognito-idp confirm-sign-up --client-id $client_id --username example_user --confirmation-code -``` +{{< command >}} +$ awslocal cognito-idp confirm-sign-up --client-id $client_id --username example_user --confirmation-code +{{< /command >}} The verification code for the user is in the e-mail you received. Additionally, LocalStack prints out the verification code in the console. The above command doesn't return an answer, you need to check the pool to see that it was successful -``` -awslocal cognito-idp list-users --user-pool-id $pool_id -``` +{{< command >}} +$ awslocal cognito-idp list-users --user-pool-id $pool_id +{{< /command >}} which should return something similar to this -
+```json {hl_lines=[20]}
 {
     "Users": [
         {
@@ -121,12 +124,11 @@ which should return something similar to this
                 }
             ],
             "Enabled": true,
-            "UserStatus": "CONFIRMED"
+            "UserStatus": "CONFIRMED"
         }
     ]
 }
-
-
+``` ## OAuth Flows via Cognito Login Form diff --git a/content/en/docs/Local AWS Services/elasticsearch/index.md b/content/en/docs/Local AWS Services/elasticsearch/index.md index 92467165b5..a4d4b8c840 100644 --- a/content/en/docs/Local AWS Services/elasticsearch/index.md +++ b/content/en/docs/Local AWS Services/elasticsearch/index.md @@ -72,7 +72,6 @@ In the LocalStack log you will see something like 2021-10-01T21:14:27:INFO:localstack.services.install: Installing Elasticsearch plugin analysis-stempel 2021-10-01T21:14:45:INFO:localstack.services.install: Installing Elasticsearch plugin analysis-ukrainian 2021-10-01T21:15:01:INFO:localstack.services.es.cluster: starting elasticsearch: /opt/code/localstack/localstack/infra/elasticsearch/bin/elasticsearch -E http.port=59237 -E http.publish_port=59237 -E transport.port=0 -E network.host=127.0.0.1 -E http.compression=false -E path.data="/opt/code/localstack/localstack/infra/elasticsearch/data" -E path.repo="/tmp/localstack/es_backup" -E xpack.ml.enabled=false with env {'ES_JAVA_OPTS': '-Xms200m -Xmx600m', 'ES_TMPDIR': '/opt/code/localstack/localstack/infra/elasticsearch/tmp'} - ``` and after some time, you should see that the `Created` state of the domain is set to `true`: diff --git a/content/en/docs/Local AWS Services/glue/index.md b/content/en/docs/Local AWS Services/glue/index.md index 751f28f3a5..457e043cb9 100644 --- a/content/en/docs/Local AWS Services/glue/index.md +++ b/content/en/docs/Local AWS Services/glue/index.md @@ -68,7 +68,7 @@ For a more detailed example illustrating how to run a local Glue PySpark job, pl The Glue data catalog is integrated with Athena, and the database/table definitions can be imported via the `import-catalog-to-glue` API. Assume you are running the following Athena queries to create databases and table definitions: -``` +```sql CREATE DATABASE db2 CREATE EXTERNAL TABLE db2.table1 (a1 Date, a2 STRING, a3 INT) LOCATION 's3://test/table1' CREATE EXTERNAL TABLE db2.table2 (a1 Date, a2 STRING, a3 INT) LOCATION 's3://test/table2' diff --git a/content/en/docs/LocalStack Tools/Lambda Tools/debugging.md.bak b/content/en/docs/LocalStack Tools/Lambda Tools/debugging.md.bak deleted file mode 100644 index f52d1dd8ff..0000000000 --- a/content/en/docs/LocalStack Tools/Lambda Tools/debugging.md.bak +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: "Remote debugging" -date: 2021-09-27 -weight: 5 -description: > - Attach a debugger to your lambdas from your IDE. ---- - -| Complexity | ★☆☆☆☆ | -|--------------|-------------------| -| Time to read | 5 minutes | -| Edition | community/pro | -| Platform | any | - -## Covered Topics - -* [Debugging JVM lambdas](#debugging-jvm-lambdas) -* Debugging Node lambdas (under development) -* Debugging Python lambdas (under development) - -## Debugging JVM lambdas - -### Configuring LocalStack service - -1. Set `LAMBDA_JAVA_OPTS` with `jdwp` settings and expose the debug port -(you can use any other port of your choice): - -```yaml -#docker-compose.yml - -services: - localstack: - ... - environment: - ... - - LAMBDA_JAVA_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=*:5050 - - LAMBDA_DOCKER_FLAGS=-p 127.0.0.1:5050:5050 -``` - -### Configuring IntelliJ IDEA - -Open the `Run/Debug Configurations` window and create a new `Shell Script` with -the following content: - -{{< command >}} -$ while [[ -z $(docker ps | grep :5050) ]]; do sleep 1; done -{{< / command >}} - -![Run/Debug Configurations](../img-inteliji-debugger-1.png) - -This shell script should simplify the process a bit since the debugger server is not -immediately available (only once lambda container is up). - -Then create a new `Remote JVM Debug` configuration and use the script from -above as a `Before launch` target: - -![Run/Debug Configurations](../img-inteliji-debugger-2.png) - -Now to debug your lambda function, simply click on the `Debug` icon with -`Remote JVM on LS Debug` configuration selected, and then invoke your -lambda function. - -### Configuring Visual Studio Code - -Make sure you installed the following extensions: -* [Language Support for Java(TM) by Red Hat](https://marketplace.visualstudio.com/items?itemName=redhat.java) -* [Debugger for Java](https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-debug) - -Add a new task by creating/modifying the `.vscode/tasks.json` file: - -```json -{ - "version": "2.0.0", - "tasks": [ - { - "label": "Wait Remote Debugger Server", - "type": "shell", - "command": "while [[ -z $(docker ps | grep :5050) ]]; do sleep 1; done; sleep 1;" - } - ] -} -``` - -Create a new `launch.json` file or edit an existing one from the `Run and Debug` tab, -then add the following configuration: - -```json -{ - "version": "0.2.0", - "configurations": [ - { - "type": "java", - "name": "Remote JVM on LS Debug", - "projectRoot": "${workspaceFolder}", - "request": "attach", - "hostName": "localhost", - "preLaunchTask": "Wait Remote Debugger Server", - "port": 5050 - } - ] -} -``` - -Now to debug your lambda function, click on the `Debug` icon with -`Remote JVM on LS Debug` configuration selected, and then invoke your -lambda function. - -## Debugging Node lambdas - -> The documentation is under development - -## Debugging Python lambdas - -> The documentation is under development diff --git a/content/en/docs/LocalStack Tools/Lambda Tools/debugging/index.md b/content/en/docs/LocalStack Tools/Lambda Tools/debugging/index.md index a17ec02296..35e8396d2e 100644 --- a/content/en/docs/LocalStack Tools/Lambda Tools/debugging/index.md +++ b/content/en/docs/LocalStack Tools/Lambda Tools/debugging/index.md @@ -38,11 +38,11 @@ There, the necessary code fragments for enabling debugging are already present. ### Configure LocalStack for remote Python debugging First, make sure that LocalStack is started with the following configuration (see the [Configuration docs]({{< ref "configuration#lambda" >}}) for more information): -```sh -LAMBDA_REMOTE_DOCKER=0 \ +{{< command >}} +$ LAMBDA_REMOTE_DOCKER=0 \ LAMBDA_DOCKER_FLAGS='-p 19891:19891' \ DEBUG=1 localstack start -``` +{{< /command >}} ### Preparing your code @@ -86,19 +86,19 @@ To create the Lambda function, you just need to take care of two things: So, in our [example](https://github.com/localstack/localstack-pro-samples/tree/master/lambda-mounting-and-debugging), this would be: -```sh -awslocal lambda create-function --function-name my-cool-local-function \ +{{< command >}} +$ awslocal lambda create-function --function-name my-cool-local-function \ --code S3Bucket="__local__",S3Key="$(pwd)/" \ --handler handler.handler \ --runtime python3.8 \ --role cool-stacklifter -``` +{{< /command >}} We can quickly verify that it works by invoking it with a simple payload: -```sh -awslocal lambda invoke --function-name my-cool-local-function --payload '{"message": "Hello from LocalStack!"}' output.txt -``` +{{< command >}} +$ awslocal lambda invoke --function-name my-cool-local-function --payload '{"message": "Hello from LocalStack!"}' output.txt +{{< /command >}} ### Configuring Visual Studio Code for remote Python debugging diff --git a/content/en/docs/LocalStack Tools/transparent-execution-mode/patched-sdks.md b/content/en/docs/LocalStack Tools/transparent-execution-mode/patched-sdks.md index 7344b70798..cd67a8b8a9 100644 --- a/content/en/docs/LocalStack Tools/transparent-execution-mode/patched-sdks.md +++ b/content/en/docs/LocalStack Tools/transparent-execution-mode/patched-sdks.md @@ -37,9 +37,9 @@ The main advantage of this mode is, that no DNS magic is involved, and SSL certi ## Configuration -If you want to disable this behavior, and use the DNS server to resolve the endpoints for AWS, you can disable this behavior using: +If you want to disable this behavior, and use the DNS server to resolve the endpoints for AWS, you can disable this behavior by using: -``` +```bash TRANSPARENT_LOCAL_ENDPOINTS=0 ``` diff --git a/content/en/docs/Understanding LocalStack/limitations.md b/content/en/docs/Understanding LocalStack/limitations.md index b2b42f766e..64ece199e8 100644 --- a/content/en/docs/Understanding LocalStack/limitations.md +++ b/content/en/docs/Understanding LocalStack/limitations.md @@ -46,7 +46,7 @@ way you'll be installing packages for `x86_64` platform. What we will be doing now is installing Java and Python executables using Homebrew, it should automatically resolve packages to proper architecture versions. -```shell +```bash # Install Homebrew /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" From 3ad52669ae966202e268bf8cfb0bc670d884b51b Mon Sep 17 00:00:00 2001 From: Alexander Rashed Date: Thu, 7 Oct 2021 09:01:22 +0200 Subject: [PATCH 7/9] fix typo in cloudformation --- content/en/docs/Local AWS Services/cloudformation/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/Local AWS Services/cloudformation/index.md b/content/en/docs/Local AWS Services/cloudformation/index.md index 523fe9756a..0efc9644ec 100644 --- a/content/en/docs/Local AWS Services/cloudformation/index.md +++ b/content/en/docs/Local AWS Services/cloudformation/index.md @@ -11,7 +11,7 @@ description: > AWS CloudFormation is AWS's primary Infrastructure-as-Code (IaC) service. It is used to declaratively define your architecture on the AWS cloud, including resources such as S3 Buckets, Lambda Functions, and much more. -CloudFormation **Stack** templates are written in either YAML or JSON and can be written manually or generated by higher-level tools such as [AWS CDK]( {{< ref "docs/integrations/aws-cdk" >}} ), [AWS SAM]( {{< ref "docs/integrations/aws-sam" >}}) [Pulumi]({{< ref "docs/integrations/pulumi" >}}) or [Serverless Framework]( {{< ref "docs/integrations/serverless-framework" >}}). +CloudFormation **Stack** templates are written in either YAML or JSON and can be written manually or generated by higher-level tools such as [AWS CDK]( {{< ref "docs/integrations/aws-cdk" >}} ), [AWS SAM]( {{< ref "docs/integrations/aws-sam" >}}), [Pulumi]({{< ref "docs/integrations/pulumi" >}}) or [Serverless Framework]( {{< ref "docs/integrations/serverless-framework" >}}). ## Quickstart From 5459ed40e55e027d75195fb6ae9a5f224d1b6249 Mon Sep 17 00:00:00 2001 From: Alexander Rashed Date: Thu, 7 Oct 2021 09:32:07 +0200 Subject: [PATCH 8/9] add command shortcode to best practices --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 873dac2604..9d817adf98 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,7 @@ alternatively: ## Best Practices Please follow these best practices when writing documentation here: +- Use the custom `command` shortcode for all one-liner commands (also when their output is presented). Do not use it for bash scripts with comments. You can find a more detailed description here: https://github.com/localstack/docs/pull/55 - Use the [`ref` or `relref` shortcode](https://gohugo.io/content-management/cross-references/#use-ref-and-relref) when creating non-external links (but still use the markdown native image linking, ref doesn't work there). You can either use `ref` or `relref`, the point is to have compile time internal-link checks (which works for both). - Stick to markdown if possible. @@ -50,6 +51,8 @@ Please follow these best practices when writing documentation here: - For snippets, define the correct syntax highlighting. Here's a list of the supported languages: https://gohugo.io/content-management/syntax-highlighting/ +- If you want to hightlight a specific line, there's a feature for that: https://gohugo.io/content-management/syntax-highlighting/#highlighting-in-code-fences + - This is also supported by the `command` shortcode! - Handling images can be a bit tedious with Hugo. If you want to use images in your post, create a new [leaf bundle directory](https://github.com/gohugoio/hugo/issues/1240) and put the image and the post (named `index.md`) in there (you can find examples in the docs already, f.e. the cognito service docs). @@ -59,4 +62,4 @@ Please follow these best practices when writing documentation here: If you want to resize the image, use the `figure` shortcode. - Use relative paths to cross-reference between pages -PS.: Feel free to add more best practices here (also give us a heads-up in [#sig-docs](https://localstack-cloud.slack.com/archives/C02FZH6UB2A)). +PS.: Feel free to add more best practices here (also give us a heads-up in [#sig-docs](https://localstack-cloud.slack.com/archives/C02FZH6UB2A)). \ No newline at end of file From b2542035a7bc3a48ddd8f89ca102c625878cb4bd Mon Sep 17 00:00:00 2001 From: Daniel Fangl Date: Thu, 7 Oct 2021 11:00:10 +0200 Subject: [PATCH 9/9] add more comments to the shortcode --- layouts/shortcodes/command.html | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/layouts/shortcodes/command.html b/layouts/shortcodes/command.html index 97fd364dcb..ccb4d19405 100644 --- a/layouts/shortcodes/command.html +++ b/layouts/shortcodes/command.html @@ -1,10 +1,13 @@ {{/* Command shortcode. Current limitations: will interpret comments as root command (# prefixes will not be selectable, use ## if this is necessary)*/}} - +{{/* The content of the shortcode has to be trimmed of newlines, in case shortcode open/close are on separate lines */}} {{ $inner := trim .Inner "\n " }} +{{/* We encapsulate, for each line, the prefix (if present) in custom prefix tags so we find it after highlighting */}} {{ $inner = replaceRE `(?m)^ *((?:\$|#) )` "###CUSTOM_PREFIX###$1###CUSTOM_PREFIX_END###" $inner}} +{{/* We need to set a default for the hightlighting options here */}} {{ $options := "" }} {{ with .Get 0 }} {{ $options = . }} {{ end }} {{ $highlighted := highlight $inner "text" $options }} +{{/* Now we replace the custom prefixes with a span that contains the prefix, which is not selectable by users */}} {{- replaceRE `###CUSTOM_PREFIX###((?:\$|#)\s)###CUSTOM_PREFIX_END###` "$1" $highlighted | safeHTML -}}