Skip to content

Run an ASP.NET Core App Locally for Elastic Beanstalk

This tutorial prepares an ASP.NET Core Web API for AWS Elastic Beanstalk by matching the Linux runtime model locally. On Linux, Elastic Beanstalk injects a PORT environment variable and proxies traffic from nginx to Kestrel.

Prerequisites

  • .NET 8 SDK installed.
  • A clean working folder.
  • curl available for endpoint checks.

What You'll Build

You will build a minimal ASP.NET Core app that:

  • Uses controllers for health and demo endpoints.
  • Binds to PORT when Elastic Beanstalk sets it.
  • Falls back to port 5000 locally.
  • Starts with dotnet GuideApi.dll from a Procfile.

Project target structure:

.
├── Controllers/
│   ├── DemoController.cs
│   └── HealthController.cs
├── GuideApi.csproj
├── Program.cs
├── Procfile
└── appsettings.json

Steps

  1. Create the project.
dotnet new webapi --framework net8.0 --use-controllers --output dotnet-aspnetcore
  1. Update Program.cs to honor PORT.
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

var portValue = Environment.GetEnvironmentVariable("PORT");
if (!string.IsNullOrWhiteSpace(portValue) && int.TryParse(portValue, out var port))
{
    builder.WebHost.UseUrls($"http://0.0.0.0:{port}");
}

var app = builder.Build();

app.MapGet("/", () => Results.Ok(new { status = "running" }));
app.MapControllers();
app.Run();
  1. Add a health endpoint and information endpoint.
[ApiController]
[Route("")]
public class HealthController : ControllerBase
{
    [HttpGet("health")]
    public IActionResult Health() => Ok(new { status = "healthy" });

    [HttpGet("info")]
    public IActionResult Info() => Ok(new
    {
        environment = Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Development",
        port = Environment.GetEnvironmentVariable("PORT") ?? "5000"
    });
}
  1. Add a demo endpoint for safe environment properties.
[ApiController]
[Route("demo")]
public class DemoController : ControllerBase
{
    [HttpGet("env")]
    public IActionResult Env() => Ok(new
    {
        ENV_NAME = Environment.GetEnvironmentVariable("ENV_NAME") ?? "local",
        APP_VERSION = Environment.GetEnvironmentVariable("APP_VERSION") ?? "not-set"
    });
}
  1. Create the Linux startup command.
web: dotnet GuideApi.dll
  1. Run the app locally.
dotnet run --project GuideApi.csproj
  1. Test both the default port and the Elastic Beanstalk-style port.
curl --silent "http://127.0.0.1:5000/health"
PORT="8080" dotnet run --project GuideApi.csproj
curl --silent "http://127.0.0.1:8080/info"

sequenceDiagram
    participant Dev as Developer
    participant Kestrel as ASP.NET Core Kestrel
    participant Nginx as Elastic Beanstalk nginx
    participant Client as curl

    Dev->>Kestrel: dotnet run
    Nginx->>Kestrel: Forward to PORT
    Client->>Nginx: GET /health
    Kestrel-->>Client: 200 JSON

Verification

Run these checks before packaging for Elastic Beanstalk:

dotnet build GuideApi.csproj
dotnet run --project GuideApi.csproj
curl --silent "http://127.0.0.1:5000/health"

Expected results:

  • The project builds cleanly.
  • Kestrel listens locally.
  • /health, /info, and /demo/env return JSON.
  • The same startup path can bind to an Elastic Beanstalk-provided PORT.

See Also

Sources