Kestrel (.NET)

intermediate

Cross-platform web server for ASP.NET Core applications.

Overview

Kestrel is Microsoft's cross-platform web server built directly into the ASP.NET Core framework, designed to handle HTTP requests with exceptional performance and lightweight resource usage. Unlike traditional web servers that require separate installation and configuration, Kestrel is embedded within .NET applications, making it the default server for all ASP.NET Core applications. It supports modern web protocols including HTTP/2 and HTTP/3, while offering built-in features like request filtering, connection limits, and SSL/TLS termination. This containerized deployment combines Kestrel with the official Microsoft .NET runtime container, creating a streamlined hosting environment for ASP.NET Core applications. The configuration utilizes the ASP.NET runtime image which includes all necessary dependencies while maintaining a smaller footprint than the full SDK image. The setup mounts a pre-published application directory and configures Kestrel to listen on HTTP port 80 with production environment settings. This stack is ideal for organizations already invested in the Microsoft ecosystem, .NET developers seeking consistent deployment across platforms, and teams requiring high-performance web applications with minimal operational overhead. The combination offers enterprise-grade performance with the flexibility of containerized deployment, making it particularly valuable for microservices architectures and cloud-native applications built on .NET technologies.

Key Features

Native HTTP/2 and HTTP/3 protocol support with automatic protocol negotiation
Built-in request size limits and connection throttling for DoS protection
Zero-allocation request processing pipeline for minimal garbage collection
Integrated health checks and metrics endpoints for monitoring
Automatic HTTPS redirection and HSTS header configuration
Socket reuse and connection pooling for improved throughput
Built-in support for gRPC services and SignalR real-time communication
Configuration through appsettings.json and environment variables without restart

Common Use Cases

1Hosting ASP.NET Core MVC web applications in containerized environments
2Deploying REST APIs and GraphQL endpoints for mobile and web clients
3Running gRPC services for high-performance inter-service communication
4Serving Single Page Applications (SPA) with ASP.NET Core backend APIs
5Microservices architecture with individual .NET service containers
6Development and staging environments matching production Kestrel configuration
7Real-time applications using SignalR for chat, notifications, or live updates

Prerequisites

Pre-compiled ASP.NET Core application published to ./publish directory
Minimum 512MB RAM allocation for basic .NET Core runtime operation
Port 80 available on host system for HTTP traffic binding
Application DLL file named MyApp.dll or modified command parameter
Basic understanding of ASP.NET Core configuration and deployment
Docker Compose version 3.8+ for proper networking and volume support

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  kestrel: 
3    image: mcr.microsoft.com/dotnet/aspnet:8.0
4    container_name: kestrel
5    restart: unless-stopped
6    working_dir: /app
7    command: dotnet MyApp.dll
8    environment: 
9      ASPNETCORE_URLS: http://+:80
10      ASPNETCORE_ENVIRONMENT: Production
11    volumes: 
12      - ./publish:/app:ro
13    ports: 
14      - "80:80"
15    networks: 
16      - kestrel-network
17
18networks: 
19  kestrel-network: 
20    driver: bridge

.env Template

.env

1ASPNETCORE_ENVIRONMENT=Production

Usage Notes

1Docs: https://learn.microsoft.com/aspnet/core/fundamentals/servers/kestrel
2Default ASP.NET Core server - built into the framework
3HTTP/2 and HTTP/3 support built-in
4Production: put behind NGINX, Caddy, or YARP for TLS termination
5Configure via appsettings.json or ASPNETCORE_* env vars
6Built-in request filtering and connection limits

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  kestrel:
5    image: mcr.microsoft.com/dotnet/aspnet:8.0
6    container_name: kestrel
7    restart: unless-stopped
8    working_dir: /app
9    command: dotnet MyApp.dll
10    environment:
11      ASPNETCORE_URLS: http://+:80
12      ASPNETCORE_ENVIRONMENT: Production
13    volumes:
14      - ./publish:/app:ro
15    ports:
16      - "80:80"
17    networks:
18      - kestrel-network
19
20networks:
21  kestrel-network:
22    driver: bridge
23EOF
24
25# 2. Create the .env file
26cat > .env << 'EOF'
27ASPNETCORE_ENVIRONMENT=Production
28EOF
29
30# 3. Start the services
31docker compose up -d
32
33# 4. View logs
34docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/kestrel/run | bash

Troubleshooting

Application fails to start with 'could not find MyApp.dll': Verify the published application exists in ./publish directory and DLL name matches command parameter
Connection refused on port 80: Check if another service is using port 80 or modify the host port mapping in docker-compose.yml
Application starts but returns 500 errors: Examine container logs with 'docker logs kestrel' and verify appsettings.json configuration for production environment
Performance issues under load: Increase Kestrel connection limits in appsettings.json or add reverse proxy like NGINX for production deployments
SSL/TLS certificate errors: Configure HTTPS URLs in ASPNETCORE_URLS and mount certificate files, or use reverse proxy for TLS termination
Memory consumption grows over time: Monitor for memory leaks in application code and consider setting memory limits in Docker Compose

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

kestreldotnet

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download