Skip to content

Update readme for path style #125

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
skyrpex merged 1 commit into from
Apr 1, 2026
Merged

Update readme for path style #125

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,12 +44,19 @@ The following environment variables can be configured:
* `AWS_ENDPOINT_URL`: The endpoint URL to connect to (combination of `USE_SSL`/`LOCALSTACK_HOSTNAME`/`EDGE_PORT` below)
* `AWS_ENDPOINT_URL_S3`: The endpoint URL to connect to (combination of `USE_SSL`/`LOCALSTACK_HOSTNAME`/`EDGE_PORT` below) for S3 requests
* `AWS_ENVAR_ALLOWLIST`: Allow specific `AWS_*` environment variables to be used by the CDK
* `AWS_S3_FORCE_PATH_STYLE`: Force path-style S3 URLs (CDK >= 2.177.0 only). Automatically enabled when `AWS_ENDPOINT_URL` hostname contains `.sandbox.`. See [Path-style S3 URLs](#path-style-s3-urls-for-remote-endpoints).
* `EDGE_PORT` (deprecated): Port under which LocalStack edge service is accessible (default: `4566`)
* `LOCALSTACK_HOSTNAME` (deprecated): Target host under which LocalStack edge service is accessible (default: `localhost`)
* `USE_SSL` (deprecated): Whether to use SSL to connect to the LocalStack endpoint, i.e., connect via HTTPS.
* `LAMBDA_MOUNT_CODE`: Whether to use local Lambda code mounting (via setting `__local__` S3 bucket name). Note: may require CDK version <2.14.0 to be fully functional.
* `BUCKET_MARKER_LOCAL`: Magic S3 bucket name for Lambda mount and [hot reloading](https://docs.localstack.cloud/user-guide/tools/lambda-tools/hot-reloading) (default: `__local__`, will default to `hot-reload` in a future release)

### Path-style S3 URLs for remote endpoints

When deploying with CDK >= 2.177.0 against endpoints whose hostname contains `.sandbox.` (e.g. `*.sandbox.localstack.cloud`), asset uploads to S3 require path-style URLs. The wildcard TLS certificate for these endpoints only covers one subdomain level and cannot match virtual-hosted-style bucket addresses like `<bucket>.abc.sandbox.localstack.cloud`.

`cdklocal` automatically enables path-style S3 when it detects a `.sandbox.` hostname in `AWS_ENDPOINT_URL`. You can also opt in explicitly via `AWS_S3_FORCE_PATH_STYLE=1`.

## Deploying a Sample App

The CDK command line ships with a sample app generator to run a quick test for getting started:
Expand All @@ -59,9 +66,9 @@ $ cdklocal init sample-app --language=javascript
...
```

Make sure that LocalStack is installed and started up with the required services:
Make sure that LocalStack is installed and started:
```bash
$ SERVICES=serverless,sqs,sns localstack start
$ localstack start
```

Then deploy the sample app against the local APIs via the `cdklocal` command line:
Expand Down
Loading