Tutorial: Hosting ASP.NET Core on Linux

ASP.NET Core is Microsoft’s cross-platform and open-source redesign of its original ASP.NET framework. With ASP.NET Core, you can build and run .NET applications not only on Windows but also macOS and Linux.

This guide shows you how to install ASP.NET Core on your Linux server and how to use it to create a web application. Then, it walks you through the steps for deploying your application using NGINX.

Before You Begin

1. If you have not already done so, create a Linode account and Compute Instance. See our Getting Started with Linode and Creating a Compute Instance guides.

2. Follow our Setting Up and Securing a Compute Instance guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access.

3. This guide uses example-app as the name of the ASP.NET Core application and example.com as your server’s domain name. Replace these with your preferred application name and actual server name, respectively.

Install ASP.NET Core

These installation steps work for Debian 10 and Ubuntu 20.04. If you are using another Linux distribution, refer to the Microsoft’s Install .NET on Linux guide.

1. Add Microsoft’s package keys and its package repository.

   • On Debian:

       wget https://packages.microsoft.com/config/debian/10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
       sudo dpkg -i packages-microsoft-prod.deb
     

   • On Ubuntu:

       wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
       sudo dpkg -i packages-microsoft-prod.deb
     

2. Update the package indices.

    sudo apt update
   

3. Install the APT package allowing you to use repositories over HTTPS and update APT’s indices again.

    sudo apt install apt-transport-https
    sudo apt update
   

4. Install the .NET Core SDK.

    sudo apt install dotnet-sdk-5.0
   

   Replace 5.0 with the latest version of the .NET Core SDK available, which you can find by running the following command:

    sudo apt search dotnet-sdk
   

   Alternatively, you can install .NET SDK using snap.

    sudo snap install dotnet-sdk
   

5. Verify the .NET Core version installed

    dotnet --version
   

Create a Web Application with .NET Core

1. Initialize a base .NET web application project.

    dotnet new webapp -o example-app
   

2. Change into the application’s directory.

    cd example-app
   

   Unless noted otherwise, all subsequent commands in this guide assume you are still in the application’s directory.

3. Run the application.

    dotnet watch run
   

   .NET Core serves the application on localhost port 5001. To visit the application remotely, you can use an SSH tunnel:

   • On Windows, you can use the PuTTY tool to set up your SSH tunnel. Follow the appropriate section of the Connecting to a Remote Server Over SSH using PuTTY guide, replacing the example port number there with 5001.

   • On OS X or Linux, use the following command to set up the SSH tunnel. Replace example-user with your username on the application server and 192.0.2.0 with the server’s IP address.

       ssh -L5001:localhost:5001 example-user@192.0.2.0
     

4. Now you can visit the application in your browser by navigating to https://localhost:5001.

   Note

   .NET Core serves your application over HTTPS. When visiting the application, you browser may warn you that the SSL certificate is self-signed. Choose to proceed anyway.

.NET Core uses Razor as its template engine for web application interfaces. You can learn more about using Razor in your web application from Microsoft’s Get started with Razor Pages in ASP.NET Core guide. .NET Core also has extensive support for developing applications using the Model–View–Controller (MVC) architecture. If you want to learn more about MVC, checkout the Microsoft’s Get started with ASP.NET Core MVC guide.

Deploy Your Application with NGINX

.NET Core’s default server, Kestrel, works well for serving dynamic web applications. However, Microsoft recommends pairing it with a reverse proxy server when deploying your application to production. Doing so allows you to offload tasks like request handling and serving static content.

The steps in this section show you how to set up NGINX as the reverse proxy server for your .NET Core application.

Install and Configure NGINX

1. Install NGINX:

    sudo apt install nginx
   

2. Create a /etc/nginx/proxy.conf file, and add the contents of the example file:

   File: /etc/nginx/proxy.conf

   1 2 3 4 5 6 7 8 9 10 11 12

   proxy_redirect off; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; client_max_body_size 10m; client_body_buffer_size 128k; proxy_connect_timeout 90; proxy_send_timeout 90; proxy_read_timeout 90; proxy_buffers 32 4k;

3. Open the NGINX configuration file — /etc/nginx/nginx.conf — and replace its contents with the following:

   File: /etc/nginx/nginx.conf

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38

   user www-data; worker_processes auto; pid /run/nginx.pid; include /etc/nginx/modules-enabled/*.conf; events { worker_connections 768; # multi_accept on; } http { include /etc/nginx/proxy.conf; limit_req_zone $binary_remote_addr zone=one:10m rate=5r/s; server_tokens off; sendfile on; keepalive_timeout 29; client_body_timeout 10; client_header_timeout 10; send_timeout 10; upstream example-app{ server localhost:5000; } server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name example.com; add_header X-Frame-Options DENY; add_header X-Content-Type-Options nosniff; location / { proxy_pass http://example-app; limit_req zone=one burst=10 nodelay; } } }

4. Open access to the HTTPS port (443) on your server’s firewall.

    sudo ufw allow https
    sudo ufw reload
   

Get an SSL Certificate

The steps below show you how to use Certbot to request and download a free certificate from Let’s Encrypt and how to add that certificate to your NGINX server.

1. Install the Snap Store. Snap provides application bundles that work across major Linux distributions. If you are using Ubuntu, Snap should already be installed (since version 16.04):

    sudo apt install snapd
   

2. Update and refresh Snap.

    sudo snap install core && sudo snap refresh core
   

3. Ensure that any existing Certbot installation is removed.

    sudo apt remove certbot
   

4. Install Certbot, and create a symbolic link for executing it.

    sudo snap install --classic certbot
    sudo ln -s /snap/bin/certbot /usr/bin/certbot
   

5. Download a certificate for your site.

    sudo certbot certonly --nginx
   

   Certbot prompts you to select from the NGINX sites configured on your machine. Select the one with your domain name.

6. Certbot includes a cron job that automatically renews your certificate before it expires. You can test the automatic renewal with the following command:

    sudo certbot renew --dry-run
   

Add the SSL Certificate to NGINX

1. Add the SSL certificate and its key to your NGINX configuration, via the ssl_certificate and ssl_certificate_key properties as shown below:

   File: /etc/nginx/nginx.conf

   1 2 3 4 5 6 7 8 9 10 11 12 13 14

   # [...] server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name example.com *.example.com; ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; add_header X-Frame-Options DENY; add_header X-Content-Type-Options nosniff; # [...]

2. Verify the NGINX configuration. Then, assuming the test passes, restart NGINX.

    sudo nginx -t
    sudo systemctl restart nginx
   

3. You can test NGINX’s routing to the application by running the application directly.

    dotnet watch run
   

Prepare the Application

The steps below ensure that your .NET Core application works properly with the NGINX reverse proxy. These steps also have you make a “published” executable of your application, which makes it easier to use in production scenarios.

1. Open the Startup.cs file, and add the Forwarded Headers middleware. Ensure that the app.UseForwarededHeaders method is invoked before any other middleware.

   File: ~/example-app/Startup.cs

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20

   // [...] using Microsoft.AspNetCore.HttpOverrides; // [...] public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { app.UseForwardedHeaders(new ForwardedHeadersOptions { ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto }); app.UseAuthentication(); // [...] } // [...]

2. Publish your application.

    dotnet publish --configuration Release
   

   The output should indicate the location of an example-app.dll file. Take note of that location, as it is used in the example-app.service file created below. It should be similar to /bin/Release/net5.0/example-app.dll.

3. Copy your project to the /var/www directory. This is a conventional place to store your production application, but it also allows you to separate your production and working versions of the application.

    sudo cp -r ~/example-dotnet-app /var/www/example-dotnet-app
   

4. Create a service file for systemd to run the application.

   File: /etc/systemd/system/example-app.service

   1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

   [Unit] Description=Example .NET Core Web Application [Service] WorkingDirectory=/var/www/example-app ExecStart=/usr/bin/dotnet /var/www/example-app/bin/Release/net5.0/example-app.dll Restart=always RestartSec=10 KillSignal=SIGINT SyslogIdentifier=dotnet-example-app User=www-data Environment=ASPNETCORE_ENVIRONMENT=Production Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false [Install] WantedBy=multi-user.target

Run the Application

1. Enable the systemd service for the published application, and then start it up.

    sudo systemctl enable example-app
    sudo systemctl start example-app
   

2. Verify that the application is running by visiting its URL, http://example.com.

Conclusion

You have now successfully created and deployed a .NET Core application. You can continue your journey and learn more about using .NET for web-application development by following Microsoft’s Recommended learning path.

More Information

You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

• Tutorial: Get Started with ASP.NET Core
• Microsofts ASP.NET Core Recommended Learning Path