Skip to content

How do I add a health check endpoint to my GreenStack site?

GreenStack checks your site’s health so it only sends visitors to containers that are running properly. Give it a dedicated endpoint using ASP.NET Core’s built-in health checks, at /health.

There are two checks:

  • Container check. Every GreenStack container requests /health on port 8080 every 30 seconds, after a 3-minute start-up grace period. This one is always on.
  • Load balancer check. With two or more replicas, the load balancer requests a path on each replica every 10 seconds, and stops sending traffic to any replica that doesn’t respond in time with a success code. You choose the path in UmbPanel. If you haven’t set one, it uses /, your home page.

Checking / works, but it renders your whole home page every 10 seconds on every replica, and a slow page, a redirect or a content error takes healthy replicas out of rotation. A /health endpoint is cheap, always answers when the app is up, and matches the path the container check already uses.

Section titled “With the UmbHost GreenStack NuGet package (recommended)”

Version 1.2.0 or later of the UmbHost GreenStack NuGet package adds /health for you, using ASP.NET Core’s built-in health checks. You don’t need to change any code. Install or upgrade it:

Terminal window
dotnet add package UmbHost.GreenStack.Umbraco.Configuration

The package answers /health before your site’s own redirects, login rules and content routing run, so none of them can get in the way. It’s only switched on inside the container, so /health doesn’t exist when you run the site locally from your IDE.

ASP.NET Core includes health checks, so there’s nothing extra to install. Register them in Program.cs, then map the endpoint after the UseUmbraco() block:

var builder = WebApplication.CreateBuilder(args);
builder.CreateUmbracoBuilder()
.AddBackOffice()
.AddWebsite()
.AddComposers()
.Build();
builder.Services.AddHealthChecks();
var app = builder.Build();
await app.BootUmbracoAsync();
app.UseUmbraco()
.WithMiddleware(u =>
{
u.UseBackOffice();
u.UseWebsite();
})
.WithEndpoints(u =>
{
u.UseBackOfficeEndpoints();
u.UseWebsiteEndpoints();
});
app.MapHealthChecks("/health");
await app.RunAsync();

Keep your existing Program.cs and add just the two lines: builder.Services.AddHealthChecks(); and app.MapHealthChecks("/health");. The example above is the Umbraco 17 template. Umbraco 13’s template also has u.UseInstallerEndpoints(); in WithEndpoints, and the two lines go in the same places.

/health returns 200 Healthy once the app is running. Check it locally by browsing to https://localhost:<port>/health.

If you add the endpoint yourself, it must be:

  • Anonymous. Don’t put it behind authentication or a members-only rule.
  • Never redirected. Leave it out of www, trailing-slash and HTTPS redirects. See How do I exclude UmbPanel domains from www redirects?.
  • Quick. Don’t add checks that call slow or external services. This applies with the package too, because it includes any checks you register. If one of them fails, every replica is reported unhealthy at once and your site goes offline.

Commit the change and deploy as usual. Once it’s live, browse to https://<your-service>.umbpanel.io/health and you should see Healthy.

  1. Open your GreenStack service in UmbPanel.
  2. Select Healthcheck.
  3. Enter /health as the Healthcheck Path. Enter a path, not a full URL.
  4. Select Save Changes.

The change applies once the deployment completes, and restarts your replicas.

The Healthcheck setting needs at least two replicas, because a health check only helps when there’s another replica to send traffic to.

My site went offline after setting the path. Every replica is failing the check. Browse to https://<your-service>.umbpanel.io/health:

  • A 404 means the endpoint isn’t deployed. Check the new image has deployed, and that it has the GreenStack package at version 1.2.0 or later, or app.MapHealthChecks("/health") in Program.cs.
  • A 503 Unhealthy means one of your own registered health checks is failing.
  • A redirect means a redirect rule is catching it. Exclude /health and *.umbpanel.io from the rule.
  • A login page means the path needs authentication. Make it anonymous.

To get the site back while you fix it, open Healthcheck and either select Disable Healthcheck or set the path back to /.