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
| Form | Install | When |
|---|---|---|
The .NET tool stellaops-router-gateway | dotnet tool install | Configuration only; every transport built in |
Your own host on StellaOps.Router.Gateway.Hosting | Your build and release process | Custom 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>
- Inside a container, the transport listens on
0.0.0.0so that the published port reaches it. Publish the transport port (9443for TLS) only on the address of the network the services use, as192.0.2.10above. - Mount certificates and keys from your platform’s secret store; never bake them into the image. A
.pfxfile needsGateway__Transports__Tls__ServerCertificatePassword, passed from the secret store as well. - TCP and UDP are for development only: they need
STELLAOPS_ROUTER_ALLOW_INSECURE_TRANSPORTS=trueand carry requests unencrypted. - Deploy images by digest, not by tag.
Health
| Path | Use it for | Answers |
|---|---|---|
/health/live | Liveness probe | 200 while the process runs |
/health/ready | Readiness probe, load balancer health | 200 when the gateway can serve; 503 until every service in Gateway:Health:RequiredMicroservices is connected |
/health/startup | Startup probe | 200 once started |
/health | Operators | The 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:
| Line | Meaning |
|---|---|
Connection registered: ... service=<name> ... with <n> endpoints | A service instance connected. |
Instance <id> ... marked Degraded / marked Unhealthy | Heartbeats are late or missing. |
Request <id> to <service> timed out after <timeout> | The gateway answered 504. |
Router licence lines | The licence monitor’s status. |
Hardening checklist
Apply the security checklist, and:
- [ ] An exact tool or package version, upgraded on purpose.
- [ ] The gateway runs as a dedicated, unprivileged user.
- [ ]
ASPNETCORE_ENVIRONMENT=Production; noappsettings.Development.jsonon servers. - [ ] Readiness probes use
/health/ready, withRequiredMicroservicesset. - [ ] Each service’s stop timeout is above its
DrainDeadline. - [ ]
Gateway:Transports:<Name>:Portis set explicitly for every enabled transport. - [ ] Logs and metrics are collected centrally.
