Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Instructions on installing Umbraco on various platforms using various tools.
The fastest way to get the latest version of Umbraco up and running is using the command line (CLI).
Open your command line.
Install the Umbraco templates:
Create a new project:
Navigate to the newly created project folder. It will be the folder containing the .csproj
file:
Build and run the newly created Umbraco site:
The console will output a message similar to: [10:57:39 INF] Now listening on: https://localhost:44388
We recommend setting up a developer certificate and running the website under HTTPS. If that has not yet been configured, run the following command:
Open your browser and navigate to that URL.
Follow the instructions to finish up the installation of Umbraco.
Members of the Umbraco Community have created a website that makes the installation of Umbraco a lot easier for you. You can find the website at https://psw.codeshare.co.uk. On the website, you can configure your options to generate the required script to run. Click on the Install Script tab to get the commands you need to paste into the terminal. This tab also includes the commands for adding a starter kit or unattended install which creates the database for you.
There are numerous ways to install Umbraco. Below, you can find links to different installation methods that will help you easily install and set up Umbraco projects.
.NET CLI, included with the .NET Software Development Kit (SDK), can be used to install or uninstall .NET templates from NuGet. This can be done by using the dotnet new
command on any OS. The underlying Template Engine enables the creation of custom templates which make new project bootstrapping much faster. With a few steps you can have an Umbraco project running without the need for a code editor.
Visual Studio is used to write native code and managed code supported by .NET and many others. Its built-in tools provide the ability to develop and execute applications for any platform. Developers will be able to install Umbraco without ever having to leave Visual Studio.
Learn how to run an already installed local installation of Umbraco.
Visual Studio Code is an editor with an embedded webserver (through the IIS Express extension). A fast way to get you up and running with Umbraco.
From Umbraco v9 and above you can use the Nightly Builds to get the latest version to use and test before it is released. Learn how to install the Nightly builds to get started.
Since Umbraco 9 it has been possible to run Umbraco CMS natively on Linux or macOS High Sierra. To get Umbraco running you will need to follow some steps.
Use the Unattended installs when spinning up Umbraco instances on something like Azure Web Apps to avoid having to run through the installation wizard.
A guide to install Umbraco CMS using Visual Studio.
Install the newest Umbraco dotnet templates.
In Visual Studio 2022, the .NET CLI templates are enabled to appear, by default. For information on how to enable .NET CLI templates in Visual Studio 2019, see the .NET CLI Templates in Visual Studio article.
Check the Requirements to ensure you have everything you need to start your Umbraco project.
This is an abbreviated version of the installation steps. Jump to the Create a new project section for a more thorough guide.
Open Visual Studio.
Go to File
> New
> Project
, search for Umbraco.
Choose Umbraco Project (Umbraco HQ) then click Next.
Choose or specify the parameters, leave the default or leave them all empty.
Click Create.
Use CTRL+F5 to run the project and start the Umbraco installer.
To install Umbraco we first need to install Umbraco's dotnet new templates.
For more information check the first 2 steps of Install Umbraco with .NET CLI.
Go to File > New > Project and search for Umbraco
in the Search for templates field.
Once you select Umbraco Project (Umbraco HQ) navigate to the next step by clicking Next.
In this step, you will be able to give your project a name specific to the project you are creating.
Refrain from changing the Solution name, as this will cause a namespace conflict with the CMS itself.
In the next step, you are able to specify some additional parameters like the Target framework. The rest are optional.
You can then click the Create button and your Umbraco Project will be ready for you.
You can now run the site through Visual Studio using F5 or the Debug button.
Follow the installation wizard and after a few steps, you will get a message saying the installation was a success.
You are now ready to start building your Umbraco project. Have a look below for different resources on the next steps.
We have made custom Umbraco templates that are available for use with dotnet new
. The steps below will demonstrate the minimum amount of actions required to get you going and set up an Umbraco project from the command line using .NET templates.
Install the latest .NET SDK.
Run dotnet new install Umbraco.Templates
to install the project templates.
The solution is packaged up into the NuGet package Umbraco.Templates and can be installed into the dotnet CLI.
Once that is complete, you can see that Umbraco was added to the list of available projects types by running
dotnet new --list
:
In some cases the templates may silently fail to install (usually this is an issue with NuGet sources). If this occurs you can try specifying the NuGet source in the command by running dotnet new install Umbraco.Templates --nuget-source "https://api.nuget.org/v3/index.json"
.
To get help on a project template with dotnet new
run the following command:
dotnet new umbraco -h
From that command's output, you will get a better understanding of what are the default template options, as well as those command-line flags specific to Umbraco that you can use (as seen below):
Create a new empty Umbraco solution:
dotnet new umbraco -n MyCustomUmbracoProject
You will now have a new project with the name MyCustomUmbracoProject, or the name you chose to use. The new project can be opened and run using your favorite IDE or you can continue using the CLI commands.
If you want to create a solution file as well you can run the commands below.
dotnet new sln
dotnet sln add MyCustomUmbracoProject
Navigate to the newly created project folder:
cd MyCustomUmbracoProject
Build and run the new Umbraco .Net Core project:
dotnet build
dotnet run
The project is now running on the Kestrel server and has assigned a free available port to run it on. Look in the terminal window after the dotnet run
command to see the URLs.
The next step is to run through the Umbraco CMS installation. If you chose to use MS SQL Server/Azure you will need to add your connection string during this setup process to get access to the Umbraco backoffice.
Follow these steps to set up an Umbraco project with VS Code. The benefit of using VS Code is that it is super quick to get up and running.
Go to https://code.visualstudio.com/ and download VS Code for free.
Once installed, launch VS Code.
Click the extensions menu at the bottom on the left side. Then search for C# and install it.
Follow the Templates Guide to create your project folder.
Open your project folder in VS Code, your project will look something like this:
Now we need to tell VS Code how to run your project.
Open the command palette, you can use the shortcut Ctrl+Shift+P
, and type in Tasks: Configure
and select the Tasks: Configure Task
option:
Select "Create task.json from template"
Now select ".NET Core" as your template.
After this VS Code will have created a folder called .vscode
that contains a file called tasks.json
, it's this file that tells VS Code how to build your project.
Now that we've told VS Code how to build your project, we need to tell it how to launch it. VS Code can do this for you. First, select the little play button in the left side menu, and then select the "create a launch.json file" link.
This will prompt a menu to appear, select .NET 5+ and .NET Core:
If .NET 5+ and .NET Core is missing in the drop-down menu:
Press Ctrl + Shift + P (on Windows/Linux) or Cmd + Shift + P (on macOS) to open the Command Palette.
Search for the command .NET: Generate Assets for Build and Debug
. This command will generate the necessary assets for building and debugging your .NET application.
Now you'll see a green play button appear with a dropdown where ".NET Core Launch (web)" is selected.
If you navigate to the Files section, a new launch.json
file is created in the .vscode
folder. When you press F5, the launch.json
file tells VS Code to build your project, run it, and then open a browser .
With that, you're ready to run the project! Press F5, or click the little green play button in the Run and Debug section to run your brand new Umbraco site locally.
This section continues from where we left off but covers the installation and configuration of Umbraco inside your web browser when you run Umbraco for the first time.
You will see the install screen where you will need to fill in some data before Umbraco can be installed.
When the installer is done, you will be logged into the backoffice.
Congratulations, you have installed an Umbraco site!
You can log into your Umbraco site by entering the following into your browser: http://yoursite.com/umbraco/.
This article describes how to run an Umbraco 9 site on a local IIS server.
This is a quick guide on getting your Umbraco website running locally on IIS.
The guide will assume you already have IIS configured and know your way around it, as well as having a local website you wish to host.
First, you need to ensure you have "Development time IIS support installed". To check this, go to the Visual Studio installer, click modify and check on the right side under "ASP.NET and web development":
Once that is installed you should set up a new IIS site - and make sure to add the hostname to your hosts file as well. Here is my setup for an example:
For the path you want to point it at the root of your site - where the .csproj
file is.
You might need to change permissions for the NuGet cache folder - C:\users\<username>\.nuget\packages
. The user or group (IIS_IUSRS) that the IIS site is running on requires Read permissions on this folder because this is where some of the files for Umbraco and Umbraco packages are being served from during development. If the IIS user or group does not have permission to read from the NuGet cache folder, you could run into a DirectoryNotFoundException
while running the site.
When the site is published these files are copied from the NuGet cache folder to wwwroot/umbraco
and wwwroot/App_Plugins
and these folders will typically have the correct permissions. For more information on setting permissions, see the File and folder permissions article.
At this point you can go to your Visual Studio solution of the site and in the Properties
folder there is a launchSettings.json
file, that looks like this:
You can add a new profile called IIS, and point it at your local domain. Here it is with my example domain:
At this point IIS will be added to the launch profiles, and you can run the site from Visual Studio by choosing IIS in the dropdown:
And finally the site is running from your local IIS:
Instructions on installing nightly builds of Umbraco.
In this article, we'll explain how you can get the latest builds of Umbraco. You can do this in three steps:
The NuGet feed containing the nightly builds is https://www.myget.org/F/umbraconightly/api/v3/index.json
.
You can either add this feed through the command line or use an IDE of your choice. In this article, we'll provide steps for:
To add the nightly feed using the command line:
Open a command prompt of your choice.
Run the following command:
Now the feed is added as a source named Umbraco Nightly
.
To add the nightly feed using Visual Studio:
Open Visual Studio.
Go to Tools > NuGet Package Manager > Package Manager Settings.
The Options window open.
Select the Package Sources option in the NuGet Package Manager section.
Click the +
icon.
A new Package source will be added automatically and highlighted.
Enter the desired name for the feed in the Name field.
Enter the link https://www.myget.org/F/umbraconightly/api/v3/index.json
into the Source field.
Click OK.
Now the feed is added as a source named Umbraco Nightly
.
To add the nightly feed using Rider:
Open Rider.
Go to View > Tool Windows > NuGet.
Go to Sources tab.
Choose the C:\Users\Úmbraco\AppData\Roaming\NuGet\NuGet.Config
to add the feed globally.
Cick the green +
button in the New Feed field.
The New feed dialog opens.
Enter the desired name in the Name field.
Enter https://www.myget.org/F/umbraconightly/api/v3/index.json
in the URL field.
Leave the User, Password fields empty, and the Enabled checkbox ticked.
Click OK.
Now the feed is added as a source named Umbraco Nightly
.
In the previous steps, we've added the feed and are now ready to install the nightly build.
However, which version should we install? This is, in particular, an issue if we want to create a new site using the dotnet template. The dotnet command does not allow us to use wildcard characters to install the newest version.
Using IDE, we can see a list of available versions in both Visual Studio and Rider. We can then use that version to install the template.
Here we're going to assume that you want to create a brand new site with the dotnet template. The approach is the same if you're updating an existing site. You'll click the Update button for the Umbraco.Cms
package instead of installing the template through the terminal.
Let's look at how we can find the latest version of the nightly build:
You can use the package manager in Visual Studio to browse the available template versions.
Open Visual Studio.
Go to Tools > NuGet Package Manager > Manage NuGet Packages For Solution...
Select Umbraco Nightly from the Package source dropdown in the NuGet - Solution window.
Check the Include prerelease checkbox.
Search for Umbraco.Templates in the Browse field.
Choose that package.
Click on the Version dropdown and see the available nightly builds.
Choose the applicable version and note down the version number.
You can use the NuGet window in Rider to browse the available template versions.
Open Rider.
Go to the Packages tab in the NuGet window..
Select Umbraco Nightly from the All Feeds dropdown.
Check the Prerelase checkbox.
Search for Umbraco.Templates in the Search field.
Choose that package.
Click on the Version drop down and see the available nightly builds.
Choose the applicable version and note down the version number
Now that our feed is added and we know the exact version we're ready to install our template.
To install the latest nightly version template:
Open your command prompt.
Run the following command using the latest version:
With that, we've successfully installed the latest nightly build of Umbraco.
All we have to do now is to create a site using the dotnet new umbraco -n MyAwesomeNightlySite
command.
For more information about installing Umbraco, see the article.
Since Umbraco 9 it has been possible to run Umbraco CMS natively on Linux or macOS High Sierra 10.13 and newer.
With Umbraco CMS on .NET Core, Linux and macOS is natively supported with SQLite as the database.
In the below section, we describe how to get started with running Umbraco CMS on Linux or macOS.
To get started with Umbraco CMS first have a look at the requirements for running Umbraco CMS.
Once you've made sure you meet the requirements it is time to install the Umbraco Templates on your system.
To do this follow the Install using .NET CLI guide.
With the templates installed on your system, it is now possible to create Umbraco projects.
To create a project, there are two options:
Continue creating projects using the .NET CLI.
Create new projects using Visual Studio (only macOS).
To create new projects using Visual Studio, you can use the Install using Visual Studio guide.
Once you create a new project it will use SQLite by default on Linux/macOS.
If you want to use an SQL server database, you will need to set up Docker.
In some cases, you might need to install Umbraco instances automatically without having to run through the installation wizard to configure the instance.
You can use the Unattended installs feature to allow for quick installation and set up of Umbraco instances on something like Azure Web Apps.
This article will give you the details you need to install Umbraco unattended.
In order to get a clean instance of Umbraco, follow our installation guide for how to Install an Umbraco project template.
As you will not be running through the installation wizard when using this feature, you need to manually tell Umbraco which database to use.
Set up and configure a new database - see Requirements for details.
Add the connection string using configuration.
Umbraco can create an SQL Server database for you during the unattended install process. The user specified by the credentials in your connection string needs to have the CREATE DATABASE
permission granted and the global setting InstallMissingDatabase is set to true
.
If your connection string is for SQLite or SQL Server Express LocalDB it is assumed that a database should be created when missing. This is regardless of the value of the InstallMissingDatabase
setting.
The 'umbracoDbDSN_ProviderName' attribute sets the .NET Framework data provider name for the DataSource control's connection. For more information on the data providers included in the .Net Framework, see the Microsoft Documentation.
A value is configured for the keyumbracoDbDSN_ProviderName
to ensure usage of the Microsoft.Data.SQLite
ADO.NET provider.
It is recommended that you make use of the values shown below for the Cache
, Foreign Keys
and Pooling
keywords on your connection string.
The unattended installs feature is disabled by default. In order to enable it, you need to add the following JSON object to a JSON configuration source.
Remember to set the value of InstallUnattended
to true
.
Alternatively you may set your configuration with Environment Variables or other means. Learn more about this in the Microsoft .Net Core config documentation.
The keys for this would then be as follows:
After completing the steps above you can now initialize the installation by booting up the Umbraco instance.
Once it has completed, you should see the following when visiting the frontend of the site.
Depending on your preferences, you can use any type of configuration to specify the connection string and login information, as well as enable unattended install. With the extending configuration functionality, it is possible to read from all kinds of sources. One example can be using a JSON file or environment variables.
Program.cs has a condition, which if met, an appsettings.Local.json file will be added and configured as a configuration source.
Having intellisense will help you to add your connection string and information needed for the unattended install.
We have added support for unattended installs with Name, Email and Password, and Connection String as CLI params, which are also available in Visual Studio. There you can fill in your information as follows: