Install Sitefinity

NOTE: To install Sitefinity CMS using NuGet, you must use Visual Studio 2017 or later. This article uses Visual Studio 2019 as a reference.

To install Sitefinity CMS in a blank web application using a NuGet package, perform the following:

Create a blank web application

To do this, perform the following:

1. Open Visual Studio.
2. In the toolbar, click File » New Project…
   The Create a new project window appears.
3. In the All languages dropdown, select C#.
4. In the All platforms dropdown, select Windows.
5. And in the All project types dropdown, select Web.
6. From the list of projects, select ASP.NET Web Application (.NET Framework).
7. In Project name, enter a name of your project.
   For example, enter SitefinityWebApp
8. Choose a location to store your project.
9. Enter a name for the solution.
   For example, enter SitefinityWebApp
10. In Framework, select .NET Framework 4.8.
11. Click Create.
12. In the window that appears, select Empty and click Create. 

Install Sitefinity CMS

IMPORTANT: When installing Sitefinity CMS 15.3 via NuGet packages, you must use the console and include the following flag to the command: -IncludePrerelease. For instance: Install-Package Progress.Sitefinity.Headless -IncludePrerelease.

In Visual Studio, perform the following:

1. In the toolbar, click Tools » NuGet Package Manager » Package Manager Console.
   The Package Manager Console opens.
2. In Package source, select All.
3. In Default project, select the empty project that you have created.
4. Install the Progress.Sitefinity.Headless package by entering in the console: Install-Package Progress.Sitefinity.Headless -IncludePrerelease

   NOTE: With these commands, you install the latest patch build. If you want to install a specific version, you must use the command followed by -Version and the version number.

   For example, enter Install-Package Progress.Sitefinity.Headless -Version 14.4.8100.0> -IncludePrerelease

5. Wait until Sitefinity CMS is installed on your empty project.
6. Build your solution.

Setup the project

1. Open the project in Visual Studio.
2. In the Solution Explorer, open the context menu of your newly created project.
3. Click View » View in browser.
   Your project starts in a browser.
4. Install your license.
   After the project initialized in the browser, the License activation page appears.
   Perform procedure Activate a license.
5. Setup the project.
   After you activate your license, the Project Startup page appears.
   Perform procedure Setup the project.
   Sitefinity CMS Dashboard appears.

In this mode, your Sitefinity can have ASP.NET Core pages only. This mode uses the following setup:

Types of pages rendered	ASP.NET Core
Backend	Sitefinity CMS (running on ASP.NET framework 4.8)
Frontend	Sitefinity ASP.NET Core Renderer (running on ASP.NET Core, rendering ASP.NET Core pages)

Create the ASP.NET Core web application

You install the Renderer in a separate ASP.NET Core application. If you do not have one, create it in the following way:

1. In Visual Studio, navigate to File » New » Project…
2. Click ASP.NET Core Web Application » Next.
3. In Project name, enter Renderer and click Create.
4. Make sure ASP.NET Core 9.0 is selected and click Create.

Install the ASP.NET Core Renderer

In your Renderer application, you must install the provided NuGet packages:

• Progress.Sitefinity.AspNetCore.nupkg
• Progress.Sitefinity.AspNetCore.Widgets.nupkg
• Progress.Sitefinity.Renderer.nupkg
  
• Progress.Sitefinity.RestSdk.nupkg
• Progress.Sitefinity.AspNetCore.FormWidgets.nupkg

Perform the following:

1. In Visual Studio, navigate to Tools » NuGet Package Manager » Package Manager Settings.
2. Under NuGet Package Manager, click Package Sources.
3. Add a new source, name it Sitefinity NuGet Repository, and, in Source field, enter https://nuget.sitefinity.com/nuget
4. Click OK.
5. Navigate to Tools » NuGet Package Manager » Manage NuGet Packages for Solution…
6. In Package source dropdown, select Sitefinity NuGet Repository.
7. Open the Browse tab, select Progress.Sitefinity.AspNetCore, and install it in project Renderer.
8. Select Progress.Sitefinity.AspNetCore.Widgets and install it in project Renderer.

Configure the ASP.NET Core Renderer

After you have created the project and installed the NuGet packages, you must configure it to connect it to Sitefinity CMS. In Visual Studio, perform the following:

1. In the Solution Explorer on the right, select appSettings.json.
   Edit the file to add the Sitefinity-related configurations.
   

   The file should look in the following way:
   

2. Select the Program.cs file.
   Edit the file to add the Sitefinity-related configurations.
   

   The file should look in the following way:
   

3. In the Solution Explorer on the right, expand Properties and select launchSettings.json.
4. Find the object with property "commandName": "Project" and edit this object’s applicationUrl property.

   The property should look in the following way:
   "applicationUrl": "https://localhost:5001;http://localhost:5000"

5. In the Visual Studio toolbar, expand the run button dropdown, and select the launch profile you just edited.
   In your case, it is named Renderer.

   NOTE: To debug your solution, you need to use the profile you have configured. Debugging of the IIS Express profile is not supported.

6. Build your solution.

Configure Sitefinity CMS

After creating and configuring your ASP.NET Core application, you have to configure your Sitefinity CMS. Perform the following:

1. In Sitefinity CMS backend, navigate to Administration » Web services.
2. Open the Default web service.
3. Under Who can access the content by this service?, select Everyone.
4. Save your changes.

Run the Renderer

To run the Renderer, navigate to https://localhost:5001/Sitefinity or http://localhost:5000/Sitefinity

NOTE: You use these URLs to run the Renderer locally for development purposes. To setup the Renderer for production, you can use on of the hosting scenarios, described in Hosting configurations.

In this mode, your Sitefinity can have ASP.NET Core pages only. This mode uses the following setup:

Types of pages rendered	Next.js
Backend	Sitefinity CMS (running on ASP.NET framework 4.8)
Frontend	Sitefinity Next.js Renderer (running on Next.js, rendering Next.jse pages)

PREREQUISITES: You must have Node.js version 18.8 or higher installed.

In this mode, the external Next.js renderer handles the requests that it can process and serves as a proxy and forwards all other requests to Sitefinity CMS. This means that it is possible to display some pages via the Next.js rendering engine and the rest could be configured to fallback to the default Sitefinity CMS rendering. For more information, see Migrate from MVC to Next.js This allows gradual page by page migration from the classic Sitefinity CMS pages to Next.js or having some of the pages rendered by Next.js and the rest handled by Sitefinity CMS. The following article describes how to setup Sitefinity CMS to work with a standalone Next.js application as renderer.

Create a Next.js application 

To create your Next.js application, perform the following: 

1. Open your terminal in the directory you want to create the application in. 
   
2. Run the following command: npx create-next-app nextjs-sitefinity --example https://github.com/Sitefinity/nextjs-samples/tree/main/src/starter-template 
   This is  the basic minimum code needed to bootstrap a standalone rendering application. Changes and updates to this would be reflected in the GitHub repository of the Next.js project. 
3. In the console, type cd nextjs-sitefinity.
4. Open the env.development file and set the SF_CMS_URL variable to point to the URL of the Sitefinity CMS proxy.
5. In the console, type npm run dev.  

To develop your website, you need access to the WYSIWYG editor and to the backend at the same time - to drop your widgets and configure them.

Running in development mode does not require installing additional software and works on any Node.js supported OS.

NOTE: The sample project runs under SSL by default and installs a default SSL certificate. To remove it, change the command configuration in the package.json file. 

Configure Sitefinity CMS

After creating and configuring your Next.js application, you have to configure your Sitefinity CMS. Perform the following:

1. In Sitefinity CMS backend, navigate to Administration » Web services.
2. Open the Default web service.
3. Under Who can access the content by this service?, select Everyone.
4. Save your changes.

Proxy logic

To have seamless experience when using the standalone renderer application together with Sitefinity CMS, the renderer is also working as a proxy and forwards every request it cannot handle to Sitefinity CMS. This way, the user does not have to switch between the two applications. This is done through the SF_CMS_URL environment variable. Setting this variable allows proxying any requests unhandled by the Next.js renderer to the CMS.

You host the renderer at your public domain and your users use only this domain, without considering whether the renderer or Sitefinity CMS handles their request.

Environment variables legend:

• (Required) 'SF_CMS_URL': The URL of Sitefinity CMS, where to proxy all of the requests that are not pages and to which all of the API call will be made.
  
• (Required) 'SF_LOCAL_VALIDATION_KEY': The secret key to work with Sitefinity Cloud. Required only when working with Sitefinity cloud for pages that are not handled by the Next.js renderer. Fore more information on the secret key, see Set up the project for local development (using Next.js Renderer)
  
• (Optional) 'NEXT_PUBLIC_SF_CMS_URL': The URL of the CMS for client-side calls, to which all of the API call will be made. Defaults to '/'.
  
• (Optional) 'SF_PROXY_ORIGINAL_HOST': Environment variable that controls the host header sent to the CMS. Useful for multisite testing locally.
  
• (Optional)'SF_HOST_HEADER_NAME': Environment variable that controls the host header sent to the CMS. Useful for cloud hosting when the original host is sent via a custom header value.
  
• (Optional)'SF_WHITELISTED_PATHS': Comma separated urls to pages made with the legacy (MVC/Web forms) frameworks so that the requests can be proxied to Sitefinity for rendering. Default is empty.
  
• (Optional)'SF_IS_HOME_PAGE_LEGACY': A flag indicating that the home page of the site is created with the legacy frameworks (MVC/Web forms) and navigation to 'www.siteurl/' will proxy the request to Sitefinity. Defaults to 'false'.
• (Optional) 'SF_WHITELISTED_WEBSERVICES': A comma-separated urls for sitefinity web services that should be allowed through the proxy.
• (Optional) 'SF_WEBSERVICE_PATH': Change the web service that the Next.js renderer instance should use. Keep in mind that a custom one should be created first in Sitefinity via Administration » Web services. The service should be enabled and its access set to Everyone. The default value is 'api/default'
  

You can use the following procedure to quickly setup your Sitefinity ASP.NET Core Renderer:

1. In Sitefinity CLI, create a new project by running:
   sf create "MyProject" --headless
2. Deploy your project to IIS and configure its port.
   For more information, see Run projects on IIS and Host Sitefinity CMS and the Renderer on the same IIS.
3. Run the .NET CLI.
4. Install the template with the following command:
   dotnet new -i Progress.Sitefinity.AspNetCore.Templates::*

   NOTE: Sitefinity comes with an ASP.NET Core Sitefinity template, which allows you to quickly setup your renderer and start using it.

5. Create a new Renderer application with the following command:
   dotnet new sitefinity --project-name "MyRenderer" --sfurl "http://your.sitefinity.url"

   Alternatively, you can create the renderer app using Sitefinity CLI by running sf create "MyRenderer" --renderer and then updating the URL to your Sitefinity CMS project in the appsettings.json of your renderer application.

6. Add a widget to your project with the following command:
   dotnet new sitefinity-widget --widget-name "YourWidgetName"

7. Start the renderer using the following command:
   dotnet run