Add static port mapping option for LocalStack docker container (fix #13)

[nazarii-piontko]

Fix #13.

The root cause is the dynamic port assignment for the HTTP endpoint, which causes the LOCALSTACK_HOST environment variable to change between runs, leading to container recreation. Ideally, the port should be configurable via LocalStackContainerOptions. However, it’s also important to keep the port dynamic when ContainerLifetime is set to Session to maintain backward compatibility.

[nazarii-piontko]

@Blind-Striker, it seems the pipeline is failing due to external issues. In my version of repo, only 2 Linux tests are failing (https://github.com/nazarii-piontko/dotnet-aspire-for-localstack/actions/runs/19018715149). Could you please help? What could be the issue?

[Blind-Striker]

@nazarii-piontko, it’s probably a permission issue. Things are a bit hectic at work today, but I’ll take a look as soon as I can.

[slang25]

I did consider this option, but the thing I'm confused about networking in aspire in general (docs), it seems that when the external and internal port are different, whatever you set LOCALSTACK_HOST will be incorrect. If you set it to the internal port, then it's correct for other containers, but incorrect for external access on the host, and if you set it to the external port (as it is today) then it's incorrect from other containers.

This PR is an improvement, but how should this work more generally? I was hoping that aspire proxies the requests, and there wouldn't be a static configured host at all.

[nazarii-piontko]

Aspire does proxy this request. However, as I understand it, LocalStack needs the LOCALSTACK_HOST variable to be set to this external port (this should probably be confirmed, it might even be safe to ignore this environment variable entirely, not sure about that, will test it later).

Also, setting a specific port value is useful for testing purposes. Imagine you’re using awslocal (or aws --endpoint-url=...) and have to adjust the command every time you restart your Aspire solution. Fixing the port avoids that. So, setting the port is about more than just persistence. It’s similar to how you configure a port for a .NET project through launchSettings.json.

[nazarii-piontko]

The only problem with this solution occurs when someone already has LocalStack running on their computer and then tries to run an Aspire project that configures a new LocalStack instance in persistent mode. In this case, the user might encounter a port allocation issue (depends on selected port), but the same thing would happen if a .NET project’s port conflicted with another process running on the machine.

[Blind-Striker]

@Blind-Striker, it seems the pipeline is failing due to external issues. In my version of repo, only 2 Linux tests are failing (https://github.com/nazarii-piontko/dotnet-aspire-for-localstack/actions/runs/19018715149). Could you please help? What could be the issue?

Hey @nazarii-piontko, I just pushed a small fix to master. Could you update this branch with the latest changes? The tests should now pass without any issues. I made the test report step fail gracefully.

[Blind-Striker]

Hey @slang25 @nazarii-piontko,

Back in the day, the reason I switched from a static port setup to a dynamic one (i.e., letting the Aspire lifecycle handle the assignment) was actually because of this issue:

👉 #4

Even though I had disabled port randomization, as documented here:

https://github.com/dotnet/docs-aspire/blob/main/docs/testing/overview.md#disable-port-randomization

Somehow, the Aspire test framework still couldn’t properly proxy requests to the LocalStack container. As a result, the library wasn’t compatible with the Aspire testing framework at that time.

Honestly, I’m not entirely sure how we managed to get past that issue now 😅

From what I can tell, since we’re setting the LOCALSTACK_HOST here:

https://github.com/localstack-dotnet/dotnet-aspire-for-localstack/blob/master/src/Aspire.Hosting.LocalStack/Internal/LocalStackConnectionStringAvailableCallback.cs#L42

it seems to work fine whether we’re using dynamic or static ports.

The tests appear to be passing cleanly, which is great.

I’m just wondering whether this concern really belongs to LocalStackContainerOptions or to LocalStackOptions (ConfigOptions)

I’ve always designed LocalStackOptions from the client’s perspective, so LocalStackContainerOptions seems to make more sense to handle this.

As far as I can see, there’s no need to modify the ConnectionStringExpression inside LocalStackResource

[Blind-Striker]

Quick question for LocalStack experts (cc: @HarshCasper - not blocking this PR, just seeking your expertise!)

In .NET Aspire, the orchestration layer automatically:

• Spins up a lightweight reverse proxy for each service
• Assigns proxy ports (can be dynamic or static)
• Handles service discovery via DNS for container-to-container communication

https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/networking-overview

The flow:

Host/External Clients
    ↓ (proxy port - e.g., 4566)
Aspire Proxy
    ↓ (container port - usually same, 4566)  
LocalStack Container

When using ContainerLifetime.Persistent (container survives app restarts), dynamic proxy ports cause Aspire to recreate the container on each run because LOCALSTACK_HOST environment variable change. This PR adds static port configuration to make persistent containers actually work (for the people who needs it)

Questions:

1. What is the primary purpose of LOCALSTACK_HOST?
2. Is it primarily for generating URLs (S3 presigned URLs, API Gateway endpoints, etc.)?
3. Is it safe to omit this variable when using Aspire's DNS-based service discovery?

All our unit and integration tests are passing ✅, so it's working in practice. Just want to ensure we're following LocalStack best practices and not setting unnecessary env vars or missing edge cases.

Thanks for any insights! 🙏