Deployment

This page puts a gateway and its services into production: install, run as a service, health and metrics, and a hardening checklist.

Choose the gateway form

FormInstallWhen
The .NET tool stellaops-router-gatewaydotnet tool installConfiguration only; every transport built in
Your own host on StellaOps.Router.Gateway.HostingYour build and release processCustom middleware, a fixed transport set, a container image of your own

Both need the .NET 10 runtime with ASP.NET Core on the machine, or the .NET 10 ASP.NET Core container image.

Install the tool

With the feed configured (Installing Stella Ops packages):

dotnet tool install StellaOps.Router.Gateway.Host --version <x.y.z-yyyyMMddTHHmmssZ> \
  --tool-path /opt/router/tools

Install an exact version on servers, and upgrade on purpose (Upgrading). The tool package carries the gateway and every assembly it runs, with the licence texts of the third-party assemblies it embeds in third-party-licenses/.

Run on Linux with systemd

The tool runs in the foreground and stops on SIGTERM. The working directory holds appsettings.json and, for TLS, the certificate files:

[Unit]
Description=Router gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=router-gateway
WorkingDirectory=/etc/router-gateway
ExecStart=/opt/router/tools/stellaops-router-gateway --urls http://0.0.0.0:8080
Environment=DOTNET_ROOT=/usr/lib/dotnet
Environment=ASPNETCORE_ENVIRONMENT=Production
Restart=on-failure
RestartSec=5
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

Run each service the same way, with a TimeoutStopSec above its DrainDeadline so that requests in flight can finish on a restart.

Run on Windows

The tool does not register with the Windows Service Control Manager. Either run it under a service wrapper that starts a console process, or build your own host, add the package Microsoft.Extensions.Hosting.WindowsServices, call builder.Host.UseWindowsService(), and register the executable with sc.exe create.

Run in a container

Build an image from your own host (the tool’s dependencies are inside its package, so a host project is the simpler image). The host must reference the server package of every transport it offers. For a gateway that offers TLS, the project references StellaOps.Router.Gateway.Hosting and StellaOps.Router.Transport.Tls.Server, and Program.cs passes the TLS server assembly (Router gateway host):

// A gateway that offers TLS only: pass the server assembly of each transport it offers.
var builder = WebApplication.CreateBuilder(args);
builder.AddRouterGatewayHost(typeof(TlsTransportServerPlugin).Assembly);

var app = builder.Build();
app.UseRouterGatewayHost();

A Dockerfile for such a project, src/Contoso.Gateway, with the nuget.config that maps StellaOps.* to the Stella Ops feed or to a folder of extracted packages (Installing Stella Ops packages):

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY nuget.config ./
COPY src/Contoso.Gateway/ src/Contoso.Gateway/
RUN dotnet publish src/Contoso.Gateway/Contoso.Gateway.csproj -c Release -o /app

FROM mcr.microsoft.com/dotnet/aspnet:10.0
WORKDIR /app
COPY --from=build /app .
USER app
ENV ASPNETCORE_URLS=http://+:8080
EXPOSE 8080 9443
ENTRYPOINT ["dotnet", "Contoso.Gateway.dll"]

The image holds no configuration, certificate or key. Pass them when the container starts:

docker run -d --name router-gateway -p 8080:8080 -p 192.0.2.10:9443:9443 \
  -v /etc/router-gateway/tls:/tls:ro \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e Gateway__Node__Region=eu1 -e Gateway__Node__NodeId=gw-eu1-01 \
  -e Gateway__Transports__Tls__Enabled=true \
  -e Gateway__Transports__Tls__BindAddress=0.0.0.0 \
  -e Gateway__Transports__Tls__ServerCertificatePath=/tls/gateway.crt \
  -e Gateway__Transports__Tls__ServerCertificateKeyPath=/tls/gateway.key \
  -e Gateway__Transports__Tls__RequireClientCertificate=true \
  -e Authentication__Schemes__Bearer__Authority=https://idp.contoso.example/realms/apps \
  -e Authentication__Schemes__Bearer__ValidIssuer=https://idp.contoso.example/realms/apps \
  -e Authentication__Schemes__Bearer__ValidAudience=router-gateway \
  registry.contoso.example/router-gateway@sha256:<digest>

Health

PathUse it forAnswers
/health/liveLiveness probe200 while the process runs
/health/readyReadiness probe, load balancer health200 when the gateway can serve; 503 until every service in Gateway:Health:RequiredMicroservices is connected
/health/startupStartup probe200 once started
/healthOperatorsThe overall state, with the informational licence object

Set Gateway:Health:RequiredMicroservices to the services without which the gateway should not take traffic.

Metrics

/metrics serves Prometheus metrics: request counts and latencies, connected instances, routing weights and the licence Endpoint gauge (stellaops_router_licence_endpoints). Scrape it from an internal network; it needs no token.

The TLS transport counts rejected certificates in the instrument router_tls_validate_rejected_total of the .NET meter StellaOps.Router.Transport.Tls, which /metrics does not include. Collect it with an OpenTelemetry metrics exporter or another meter listener in your host.

Logs

The gateway and the services log through Microsoft.Extensions.Logging. Useful lines:

LineMeaning
Connection registered: ... service=<name> ... with <n> endpointsA service instance connected.
Instance <id> ... marked Degraded / marked UnhealthyHeartbeats are late or missing.
Request <id> to <service> timed out after <timeout>The gateway answered 504.
Router licence linesThe licence monitor’s status.

Hardening checklist

Apply the security checklist, and: