To aid in developing Umbraco with additional services, the templates can provide the requisite files to run Umbraco with an SQL Server database in Docker. This setup is designed to be used for local development, and not for production.

Prerequisites

Before you can run Umbraco in Docker, you need to have the following installed:

• Version 14.3.0 or higher of the Umbraco Templates

• Docker Desktop

Installing

Installing Umbraco with the Docker file and Docker Compose file is a two-step process.

1. Create a folder to hold your project and enter that folder.

mkdir MyDockerProject
cd MyDockerProject

1. Create your Umbraco project using the Umbraco Templates, and remember to use the --add-docker flag to include the Docker files.

Conventionally this is named the same as the folder, but it is not a requirement.

dotnet new umbraco -n MyDockerProject --add-docker

Now we need to add some additional files to make docker compose work. We can do this using the umbraco-compose template, passing the project name we specified earlier to the -P parameter:

dotnet new umbraco-compose -P "MyDockerProject"

The -P flag is required to specify the correct paths in the docker-compose file. The project is now ready to run with docker compose.

The final folder structure looks like this:

• MyDockerProject

  • MyDockerProject

    • Typical project files

    • DockerFile

    • .dockerignore

  • .env

  • Database

    • DockerFile

    • healthcheck.sh

    • setup.sql

    • startup.sh

  • docker-compose.yml

The project now includes docker files for both Umbraco and the SQL server database.

It also includes additional scripts to launch and configure the database and a .env file with the database password.

Running

To run the project use the docker compose up command in the root of the project files where the docker-compose.yml is.

This command will build both the Umbraco and SQL Server images and launch them in the correct order. When the site is booted, access it in your browser on http://localhost:44372/.

Useful commands

There are some useful commands you can use to manage the docker containers:

• docker compose down --volumes: Delete your containers and the volumes they use. This is useful if you want to start from scratch.

• docker compose up --build: Rebuild the images and start the containers. This is useful if you have made changes to the project and want to see them reflected on the running site.

• docker compose watch: Start the containers and watch the default models folder. This means that if the project uses a source-code models builder the images are automatically rebuilt and restarts when you change the models.

Details

The docker compose file uses bind mounts for the following folders:

• /wwwroot/media

• /wwwroot/scripts

• /wwwroot/css

• /Views

• /models

This is not meant to be used in production.

For local development, however, this means that the files necessary for development are available from outside the container in your IDE. This allows development even though the project is running in docker.

Template options

The umbraco-compose template has a few options that can be used to customize the setup:

• -P or --project-name: The name of the project. This is required and used to set the correct paths in the docker-compose file.

• -dbpw or --DatabasePasswor: Used to specify the database password. This is stored in the .env file and defaults to: Password1234.

• -p or --Port: Used to specify the port the site will run on. Defaults to 44372.

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.

Video Tutorial

Install the template

Once that is complete, you can see that Umbraco was added to the list of available projects types by running dotnet new --list:

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 an Umbraco project

1. 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.

Run Umbraco

1. Navigate to the newly created project folder: cd MyCustomUmbracoProject

2. Build and run the new Umbraco .Net Core project: dotnet build dotnet run

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.

Prerequisites

• Install the newest .

  • 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 article.

• Check the to ensure you have everything you need to start your Umbraco project.

Quick Start

This is an abbreviated version of the installation steps. Jump to the 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.

Video Tutorial

Create a new Umbraco project

To install Umbraco we first need to install Umbraco's dotnet new templates.

Create the Visual Studio project

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.

Configure project

In this step, you will be able to give your project a name specific to the project you are creating.

Additional information

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.

Running the site

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.

Next steps

You are now ready to start building your Umbraco project. Have a look below for different resources on the next steps.

Install Umbraco using CLI

The fastest way to get the latest version of Umbraco up and running is using the command line (CLI).

1. Open your command line.

2. Install the Umbraco templates:

1. Create a new project:

1. Navigate to the newly created project folder. It will be the folder containing the .csproj file:

1. Build and run the newly created Umbraco site:

1. The console will output a message similar to: [10:57:39 INF] Now listening on: https://localhost:44388

1. Open your browser and navigate to that URL.

2. Follow the instructions to finish up the installation of Umbraco.

Alternative Methods for Installing Umbraco

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.

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.

Setting up prerequisites

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:

Add permissions to NuGet cache folder

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.

Add new launch profile

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:

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.

How to get started 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.

Get clean install of Umbraco

In order to get a clean instance of Umbraco, follow our installation guide for how to Install an Umbraco project template.

Configure your database

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.

SQL Server Example in appsettings.json

{
  "ConnectionStrings": {
    "umbracoDbDSN": "server=localhost;database=UmbracoUnicore;user id=sa;password='P@ssw0rd'",
    "umbracoDbDSN_ProviderName": "System.Data.SqlClient"
  }
}

SQLite Example in appsettings.json

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.

{
  "ConnectionStrings": {
    "umbracoDbDSN": "Data Source=|DataDirectory|/Umbraco.sqlite.db;Cache=Private;Foreign Keys=True;Pooling=True",
    "umbracoDbDSN_ProviderName": "Microsoft.Data.Sqlite"
  }
}

Enable the unattended installs feature

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.

{
  "Umbraco": {
    "CMS": {
      "Unattended": {
        "InstallUnattended": true,
        "UnattendedUserName": "FRIENDLY_NAME",
        "UnattendedUserEmail": "EMAIL",
        "UnattendedUserPassword": "PASSWORD"
      }
    }
  }
}

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:

Umbraco__CMS__Unattended__InstallUnattended
Umbraco__CMS__Unattended__UnattendedUserName
Umbraco__CMS__Unattended__UnattendedUserEmail
Umbraco__CMS__Unattended__UnattendedUserPassword

Initialize the unattended install

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.

Configuration options

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.

#if DEBUG
  .ConfigureAppConfiguration(config
    => config.AddJsonFile(
      "appsettings.Local.json",
      optional: true,
      reloadOnChange: true))
#endif

Having intellisense will help you to add your connection string and information needed for the unattended install.

{
    "ConnectionStrings": {
        "umbracoDbDSN": "server=localhost;database=UmbracoUnicore;user id=sa;password='P@ssw0rd'"
    },
    "Umbraco": {
        "CMS": {
            "Unattended": {
                "InstallUnattended": true,
                "UnattendedUserName": "FRIENDLY_NAME",
                "UnattendedUserEmail": "EMAIL",
                "UnattendedUserPassword": "PASSWORD"
            }
        }
    }
}

More support

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:

CLI

dotnet new umbraco -n MyNewProject --friendly-name "Friendly User" --email user@email.com --password password1234 --connection-string "Server=(localdb)\Umbraco;Database=MyDatabase;Integrated Security=true" --version 10.0.0

Visual Studio

In this article, we'll explain how you can get the latest builds of Umbraco. You can do this in three steps:

1. Adding the nightly feed as a NuGet source

2. Finding the latest nightly version

3. Installing the latest nightly version template

Adding the nightly feed as a NuGet source

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:

• Using the command line

• Using Visual Studio

• Using Rider

Option 1: Using the command line

To add the nightly feed using the command line:

1. Open a command prompt of your choice.

2. Run the following command:

dotnet nuget add source "https://www.myget.org/F/umbraconightly/api/v3/index.json" -n "Umbraco Nightly"

Now the feed is added as a source named Umbraco Nightly.

Option 2: Using Visual Studio

To add the nightly feed using Visual Studio:

1. Open Visual Studio.

2. Go to Tools > NuGet Package Manager > Package Manager Settings.

1. The Options window open.

2. Select the Package Sources option in the NuGet Package Manager section.

3. Click the + icon.

4. A new Package source will be added automatically and highlighted.

5. Enter the desired name for the feed in the Name field.

6. Enter the link https://www.myget.org/F/umbraconightly/api/v3/index.json into the Source field.

7. Click OK.

Now the feed is added as a source named Umbraco Nightly.

Option 3: Using Rider

To add the nightly feed using Rider:

1. Open Rider.

2. Go to View > Tool Windows > NuGet.

3. Go to Sources tab.

4. Choose the C:\Users\Úmbraco\AppData\Roaming\NuGet\NuGet.Config to add the feed globally.

5. Cick the green + button in the New Feed field.

1. The New feed dialog opens.

2. Enter the desired name in the Name field.

3. Enter https://www.myget.org/F/umbraconightly/api/v3/index.json in the URL field.

1. Click OK.

Now the feed is added as a source named Umbraco Nightly.

Finding the latest nightly version

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:

• Using Visual Studio

• Using Rider

Option 1: Using Visual Studio

You can use the package manager in Visual Studio to browse the available template versions.

1. Open Visual Studio.

2. Go to Tools > NuGet Package Manager > Manage NuGet Packages For Solution...

1. Select Umbraco Nightly from the Package source dropdown in the NuGet - Solution window.

1. Check the Include prerelease checkbox.

2. Search for Umbraco.Templates in the Browse field.

3. Choose that package.

4. Click on the Version dropdown and see the available nightly builds.

5. Choose the applicable version and note down the version number.

Option 2: Using Rider

You can use the NuGet window in Rider to browse the available template versions.

1. Open Rider.

2. Go to the Packages tab in the NuGet window..

3. Select Umbraco Nightly from the All Feeds dropdown.

1. Check the Prerelase checkbox.

2. Search for Umbraco.Templates in the Search field.

3. Choose that package.

4. Click on the Version drop down and see the available nightly builds.

5. Choose the applicable version and note down the version number

Installing the latest nightly version template

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:

1. Open your command prompt.

2. Run the following command using the latest version:

dotnet new install Umbraco.Templates

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 Installation article.

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.

Installing and setting up VS Code

1. Go to https://code.visualstudio.com/ and download VS Code for free.

2. Once installed, launch VS Code.

3. Click the extensions menu at the bottom on the left side. Then search for C# and install it.

Creating your Umbraco project

Follow the Templates Guide to create your project folder.

Configure VS Code to run the Umbraco project

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:

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.

Umbraco Web Installer

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!