In this tutorial, you will learn how to install Umbraco v9 using the .NET CLI tool. Released on the 28th of September 2021, v9 is the first Umbraco release that fully supports .NET Core. I will show you how to set up a development environment on your Windows PC and then I will walk you through the required steps to install Umbraco v9 and a sample site. The great thing about v9 is that it is fully .NET Core compatible. This means that if you are an Apple fan, you can now build Umbraco sites on a MAC. Even though you can build Umbraco sites on a MAC, pretty much 99% of Umbraco developers come from a Windows background. This is why this guide is aimed at Windows users. This guide will assume you are using a Windows machine too 😊😊
PRE-REQUISITES
Before you can get Umbraco up and running, you need to ensure that your PC has all the recommended pre-flight checks covered. In simple terms, you need to have the correct software installed before Umbraco will work. Before trying to install V9, make sure you have all of these pre-requisites installed locally:
- ASP.NET 5: This is needed to power the framework
- .NET CLI: This will be installed while you install ASP.NET 5
- Windows Hosting Bundle: This is needed to allow you to host your website in IIS
- Microsoft Visual Studio 2019 version 16.8 or higher: Umbraco will not install otherwise!
- IIS
- SQL Server 2019 with SSMS
- Docker (optimal)
If you work with .NET Core a lot, you will likely have most of these pre-requisites installed already. For this walk-through, I will show you how to install Umbraco via the terminal alone 💥💥. To do any development work, I still recommend using Visual Studio. If you want to use Visual Studio it must be patched to the correct version otherwise things will not work.
DATABASE CONFIGURATION
When Umbraco installs by default, it will install the database within your websites App_Data folder. In order to get a sample site up and running quickly, a file based SQL database will suffice, however, if you want to work optimally you will be better off hosting the database within SQL server. When your database is hosted within SQL, you can use SSMS to make back-ups, perform SQL queries and transfer data to remote sources (like Azure) easily.
Installing a SQL server locally is simple enough, you need a few things
- Install SQL Server Express (with SQL Server Management Studio)
- Set SQL server to all mixed-mode authentication (SQL and Windows Authentication)
- Set up a SQL account (you could use the sa account)
If you use 'sa' make sure the account is enabled and allowed for remote access. Create a blank database that the Umbraco install can use later
IIS SET-UP
If you can only access your site solely when the Visual Studio debugger is running, or when doing a dotnet run then you will not be working in an efficient way. Relying on these methods to view the site will cause a lot of hassle. If you need to launch Visual Studio every time you want to view the site, you will be wasting valuable time. Instead, it will be a lot more useful if you configure a local webserver to allow your website to be accessible 24/7 via a web browser (without the need for anything else to be running in the background).
Installing a webserver (IIS) and setting up a website is easy, however, you will also need to configure a local hostname. This hostname is the URL that you will type into a browser to access the website. In order to set up a hostname, you will need to add an entry within your host file. The host file is located here:
C ➡ Windows ➡ System32 ➡ etc ➡ drivers
You will only be able to update the host file in a text editor that has administrator privileges. Within the host file, you need to create a map between your chosen hostname to localhost (127.0.0.1). Creating this map will mean that when someone types in the hostname in a browser, the request will be redirected to the local web server, instead of the internet. The hostname will be used to route the request to the correct website in IIS. To create this mapping is simple, add the IP address 127.0.0.1 first, add a tab and then add your chosen hostname, like this:
Now, when you type http://myWebsiteUrl into a browser the request should load your website. As you have yet to install Umbraco you will know it has worked if you see an error (usually a 403 error)! Within IIS you will need to create a new website. In order to create a new website, you need three things, a name, a folder location and a hostname. Call the website in IIS anything you want as you will be the only person viewing it. Use the hostname you created above. Finally, point the folder location to the area on your PC where you will install the CMS files shortly.
When trying to view your website, it is also possible that you will bump into a Windows file access permission error. To fix the permission error you need to set the correct folder permissions on your web folder. The easy way to set permissions is within IIS. Right-click on the website entry and select permissions. The permissions I recommend you add are:
- NETWORK SERVICE
- IIS AppPool\ApplicationPoolName
CONFIGURING UMBRACO
From v9 onwards, there is a new way to install Umbraco via the CLI. Being able to install Umbraco solely within a terminal makes me happy 😃. In case you are worried about having to learn lots of new syntaxes, all you really need to know is three commands to get Umbraco up and running. As we install everything via a terminal it is also much quicker than before 😍.
In a terminal, make sure you navigate to the folder where you want to install the site. You are now ready to enter in your first command! The first command will install the Umbraco template. You can then use the template to install Umbraco. Installing the template is done using this command:
With the Umbraco template installed, you can now create a new Umbraco project using this command:
Where MyProject should be replaced with your project name. The installation process took me about 2 minutes so it is super-quick. After doing this, you can run and start your new Umbraco V9 website using this terminal command:
When the site starts, the URL that you will need to use to load the site will be displayed in the terminal window:
INSTALLING THE CMS
After typing the URL into a browser, the Umbraco installer will start. On the first screen, you will need to create the admin account that you will use to access the backend (/umbraco). On the next screen, you will decide where to install the database. Select the SQL server you installed in the pre-requisites section, the SQL username and password you created earlier and the database name:
If everything has gone according to plan, the Umbraco backend should load automatically. If not, add /umbraco to the end of the development URL and you should see the login screen. Use the admin username and password you created during the Umbraco installation process to log in:
When Umbraco first installs it will be very vanilla and empty. You will have a blank slate to start with. A blank slate is great if you are a Umbraco ninja 🐱👤. A blank slate is not great for Umbraco newbies. If you are new to Umbraco, I recommend you install a sample site to make your life easier. Installing the sample site is dead simple and takes minutes. In the Umbraco backend, go to the packages section and navigate to the starter site tab:
As you can see, you will get access to the command required to install the sample pages:
Copy the command and run it in a terminal. Now re-build the solution:
When the website re-loads, the homepage should be replaced with the starter kits homepage:
You should not be in a much better position to start learning about the mightly power of Umbraco CMS 💥💥💥
CONFIGURING IIS
The last task is to finish hooking up our new site in IIS. We have a website in IIS created, however, there are a few extra steps required before it our site will resolve correctly. Let us fix that. .NET Core works slightly differently compared to the classic ASP.NET framework. First, you need to install a new .NET core IIS module. Ensure you have the Windows Hosting Bundle (download here) installed. After installing this module, you will either need to reboot your PC, or you will need to reboot IIS. You can reset IIS in a terminal, using these two commands:
The next step is to make sure that the application pool CLI type is set to No Managed Code:
With the application pool set up correctly, you now need to publish the solution. Publishing the solution will give you the web.config and all the files required to run the site. This can be done in the terminal using this command:
At the end of the publishing process, you should see the output folder location in the terminal log. On my laptop, my files were located in this folder:
C:\POC\umbraco9\bin\Debug\net5.0\publish\
Set this location as the main website folder location in IIS, like this:
That's all there is to get a Umbraco v9 sample site up and running and ready for development. Even though the process is slightly different compared to previous versions of Umbraco, after you get used to the CLI commands you will appreciate how much easier and quicker it is. This has been episode 1 in my Umbraco v9 series, keep your eyes peeled for more 👀👀 Happy Coding 🤘
