Start To Finish: Kentico Cloud .Net Core 2.2 MVC Boilerplate on Ubuntu 18.04 Using Nginx Reverse Proxy

A growing trend lately on the internet is the use of Headless CMS. To me, it seems like just another buzzword, but if you do any research you will find all the benefits. The main one being separating all your content from how it is displayed. Doing this allows content editors to do their job without stepping on the developer's toes. This allows the developers to work at the same time the editors eliminated the bottleneck of one waiting for the other. One of the more polished Headless CMS vendors out there is Kentico Cloud. I may be a little biased, but I was blown away by how easy it is to get up and running, and to top it off their starter plan is free so you can get your feet wet and play with the great feature set. 

This tutorial will guide you in creating a foundation to get you started with a Kentico Cloud powered application. I am choosing to use .NET MVC Core2.2 but there are several other platforms available. And of course, content coming from Kentico Cloud. In this tutorial, I’ll be using the sample site that is available so all the content is already there. 

Ubuntu Server 18.04 LTS

.NET MVC Core2 is cross-platform which allows for many possible choices for a server platform. Since I’m a supporter of open source software my choice is Ubuntu Server 18.04 LTS (long term support). You also get a 10-year lifecycle which means you’ll continue to get security updates for that timeframe. 

Kestrel, What Is It?

ASP.Net MVC Core2 relies on the Kestrel web server to handle the requests to your application and is installed by default. Kestrel is an open source cross-platform web server. Even through Kestrel can serve web pages just like IIS you will need to use a reverse proxy to server pages to those other than localhost. Kestrel is really just a command line application designed for speed. Because of its lightweight design it is missing security, compression, and caching, something a full fledged web server should have. Again, this makes it FAST.

Introducing nginx

For the reverse proxy, nginx (pronounced engine-x) fits the bill. Nginx sits between Kestrel and the internet. It handles all the stuff that Kestrel wasn’t designed to do by sanitizing and passing the requests on. It is also super fast and able to handle a high volume of traffic with a small memory footprint. Once again nginx is open source so there are no licensing fees required. 

Let's get started

Server Install using Vultr

Vultr is a high-performance cloud host that I’ve used for several years and they make server installs super easy. You can have a VM up and running in the time it takes to brew a pot of coffee. They’re also pretty inexpensive with plans starting at just $2.50 a month. For this tutorial, I’ve gone with their 1CPU/2GB package at only $10 a month which is more than enough for most simple sites.

Ubuntu Configuration

Once the server is all up and running we need to get it ready for MVC Core 2 app hosting. We’ll be installing the MVC Core2 runtime as well as nginx.

Add a User

We first need to add a user that will log into that is not root. Logging into root is not recommended since you can fat finger yourself to server collapse. This step is only necessary if you are using the pre-packaged Ubuntu installation provided by Vultr. The normal Ubuntu Server installation will have you do this during setup

adduser myuser 

Add user to the Sudo Group

To run elevated commands our user needs to be added to the sudo group

usermod -aG sudo myuser

Change to the New User

Let’s be safe and run as non-root

su myuser 
cd

Add an Application User

The application will need its own user. This is similar to the name of an app_pool in the IIS world. This allows us to set file permissions on what our MVC app has access to.

sudo adduser dancinggoat 

Add Root Directory for our Application

This is where our app will reside. Most tutorials will have you put it in /var/www which is great if it’s the only site on the web server. I like to put my sites in the home directory of the user that’s running it.

sudo mkdir /home/dancinggoat/dancinggoat.com 

Change Permissions

We need to make sure our app user can access the directory.

sudo chown dancinggoat:dancinggoat /home/dancinggoat/dancinggoat.com 

Disable Root SSH Login

Let’s disable the root user so there are no mistakes. Be sure you can successfully log into the user account we created at the beginning. By default, sshd does not allow root ssh so all we need to do is comment the line out.

sudo vim /etc/ssh/sshd_config

#comment out the line
#PermitRootLogin yes

sudo service sshd restart

Install .Net Core Runtime

To install the ASP.Net MVC Core2 runtime we need to add the Microsoft apt package repository, be sure to update the available package list and install the runtime.

https://dotnet.microsoft.com/download/linux-package-manager/ubuntu18-04/runtime-2.1.2

wget -q https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo add-apt-repository universe 
sudo apt-get install apt-transport-https 
sudo apt-get update 
sudo apt-get install aspnetcore-runtime-2.2

Install Nginx

Installing nginx is pretty straight forward.

sudo apt-get install nginx

Configure Nginx

We need to create a new configuration file in the /etc/nginx/sites-available. We can use the below example to get you started. Wherever the Dancing Goat domain is, replace it with your domain. This will setup nginx to pass any requests to your domain to localhost port 5000 which is the default Kestrel listening port. Configure a reverse proxy server here.

cd /etc/nginx/sites-available
sudo vim dancinggoat.config
server {
    listen        80;
    server_name   dancinggoat.com *.dancinggoat.com;
    location / {
        proxy_pass         http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
    }
}

Make symlink to Enable Site

To enable the sites we need to create a sym-link so nginx knows to include the site when it starts up. 

cd ../sites-enabled
sudo ln -s ../sites-available/dancinggoat.config .

Create Service for ASP.Net Core2 App

Even though you can start Kestrel from the command line, doing that in a normal server setup isn’t very practical. You’d need to manually start the app every time the server boots and also if it crashes. Since Ubuntu uses systemd to manage services we’ll need to create a new service for it to run.

sudo vim /etc/systemd/system/dancinggoat.service
[Unit]
Description=Kentico Cloud Boilerplate Example

[Service]
WorkingDirectory=/home/dancinggoat/dancinggoat.com
ExecStart=/usr/bin/dotnet /home/dancinggoat/dancinggoat.com/DancingGoat.dll
Restart=always
# Restart service after 10 seconds if the dotnet service crashes:
RestartSec=10
KillSignal=SIGINT
SyslogIdentifier=dotnet-dancinggoat
User=dancinggoat
Environment=ASPNETCORE_ENVIRONMENT=production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target

Install the Kentico Cloud MVC Core2 Boilerplate and Publish to Ubuntu

Now it’s time to jump over to a windows command line to do some local work. We’ll be adding the Kentico Cloud Boilerplate and creating our project.

mkdir C:\src\dancinggoat
cd C:\src\dancinggoat
dotnet new --install "KenticoCloud.CloudBoilerplateNet::*"
dotnet new kentico-cloud-mvc --name "DancingGoat"
cd DancingGoat
dotnet run

Update IIS Rewrite

The boilerplate contains a redirect rule that is set for example.com that we need to update using our domain.

Rename all occurrences of example.com to dancinggoat.com

cd C:\src\dancinggoat\DancingGoat
vim IISUrlRewrite.xml

Publish Boilerplate

Now we’re ready to publish our app. First, we need to create a new directory to keep our published application. Make sure the target directory is outside of your development tree or you will recursively publish the app if you go through the publish process more than once. The parameters below selects the Release configuration and set a target framework of ASP.Net MVC Core2.2

https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-publish?tabs=netcore21

mkdir ..\published
dotnet publish -c Release -f netcoreapp2.2 -o ..\published

Send Published Code to Ubuntu

Now it’s time to send the published application over to our Ubuntu VM. Since I’ve installed git integrated in the windows command line I can use scp to send that over. You could use a gui app such as FileZilla, Putty pscp or any other way to transfer the entire directory to the target.

cd ..\published
scp -r * dancinggoat@dancinggoat.com:~/dancinggoat.com/

Almost Done, Back to Ubuntu.

We’ve made it this far and we’re almost done. The last steps to go are enabling the Kestrel service and restarting nginx. 

Enable and Start the New Service

sudo systemctl enable dancinggoat.service
sudo systemctl start dancinggoat.service
sudo systemctl status dancinggoat.service

Reload nginx config

sudo service nginx reload

All Done!

Obviously, this tutorial is just to get you started but it touches a little bit of everything from hosting, developing, and publishing a completed app. If you’ve done everything properly you should be able to view the Kentico Cloud demo on the domain of your configuration.