# Install Sitefinity

## Overview

You first install Sitefinity CMS in headless mode and then, you install the standalone Renderer application - ASP.NET Core or Next.js. Finally, you configure Sitefinity CMS to work with the Renderer of your choice.

## Install Sitefinity CMS

Before installing and configuring the Renderer of your choice, you must have installed Sitefinity CMS.\
To do so, use the following procedure.

<SfDetails summary="Install Sitefinity CMS">

> info **NOTE**: This article uses Visual Studio 2022 as a reference.

To install Sitefinity CMS, first configure the Sitefinity NuGet package sources, create a blank application and then install Sitefinity CMS via the NuGet Package Manager Console.

### Configure Sitefinity NuGet package sources

All the latest Sitefinity NuGet packages are uploaded to [NuGet.org](https://www.nuget.org/). There are certain third-party, legacy and proprietary packages that are not available on NuGet.org but are hosted on [Sitefinity NuGet repository](http://nuget.sitefinity.com/#/home). Therefore, we recommend configuring and using both repositories as package sources.

In Visual Studio, perform the following:

1. In the toolbar, click *Tools » NuGet Package Manager » Package Manager Settings*.
2. In the left pane, expand *NuGet Package Manager*.
3. Select *Package Sources*.
4. Add a new source by clicking the plus (+) button.
5. Configure NuGet.org repository in the following way:
   * In *Name*, enter: `NuGet.org`
   * In *Source*, enter: `https://api.nuget.org/v3/index.json`
6. Add a new source by clicking the plus (+) button.
7. Configure Sitefinity NuGet repository in the following way:
   * In *Name*, enter: `Sitefinity NuGet`
   * In *Source*, enter: `https://nuget.sitefinity.com/nuget`
8. To save your changes, click *OK*.

### Create a blank web application

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 opens, select *Empty* and click *Create*.

### Install Sitefinity CMS

> important **IMPORTANT**: When installing Sitefinity CMS via NuGet packages, you must use the Package Manager console, select the *All* option from the *Package source* dropdown, and use the `Install-Package` command with included `-IncludePrerelease` flag.

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 latest `Progress.Sitefinity.Headless` NuGet package by entering in the console:\
   `Install-Package Progress.Sitefinity.Headless -IncludePrerelease`

   > info **NOTE**: If you want to install a specific version of the package, you must include `-Version <Version>` and `-IncludePrerelease` flags in the command. For example, enter:\
   > `Install-Package Progress.Sitefinity.Headless -Version 15.4.8630 -IncludePrerelease`
5. Wait until NuGet finishes installing all Sitefinity CMS packages in your empty project.

   > info **NOTE**: Visual Studio may display a *Conflicting File Modification* dialog about changes made in your project file. In this case, resolve the conflicting changes by clicking *Overwrite*.
6. Build your solution.

### Set up 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 opens.\
   Perform the procedure [Activate a license](https://www.progress.com/documentation/sitefinity-cms/activate-a-license).
5. Set up the project.\
   After you activate your license, the *Project Startup* page opens.\
   Perform the procedure [Set up the project](https://www.progress.com/documentation/sitefinity-cms/set-up-the-project).

</SfDetails> 

> info **NOTE**: If you have already installed Sitefinity CMS, you can proceed by installing the Renderer using one of the procedures in section **Next steps** below.

## Next steps

After installing Sitefinity CMS, you install the Renderer of your choice by performing one of the following procedures:

<SfDetails summary="Install Sitefinity ASP.NET Core Renderer">

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

<table>
<tbody>
<tr>
<td>

**Types of pages rendered**

</td>
<td>

ASP.NET Core

</td>
</tr>
<tr>
<td>

**Backend**

</td>
<td>

Sitefinity CMS
(running on </em><strong><em>ASP.NET Framework 4.8</em></strong>)

</td>
</tr>
<tr>
<td>

**Frontend**

</td>
<td>Sitefinity ASP.NET Core Renderer
(<em>running on <strong>ASP.NET Core</strong>, rendering ASP.NET Core pages</em>)
</td>
</tr>
</tbody>
</table>

### Create the ASP.NET Core 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 Empty* application » *Next*.
3. In *Project name*, enter `Renderer` and click *Create*.
4. In *Framework*, make sure *.NET 10.0 (Standard Term Support)* 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* » *Manage NuGet Packages for Solution…*
2. In the *Package source* dropdown, select *NuGet.org*.
3. Open the *Browse* tab, select *Progress.Sitefinity.AspNetCore* and install it in project *Renderer*.
4. Repeat the same step for each of the remaining NuGet packages (listed above this procedure).

### 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:
   ```JSON
   {
     "Logging": {
       "LogLevel": {
         "Default": "Information",
         "Microsoft": "Warning",
         "Microsoft.Hosting.Lifetime": "Information"
       }
     },
     "AllowedHosts": "*",
     "Sitefinity": {
       "Url": "https://yoursitefinitywebsiteurl",
       "WebServicePath": "api/default"
     }
   }
   ```
2. Select the `Program.cs` file.\
   Edit the file to add the Sitefinity-related configurations.\
   The file should look in the following way:
   ```C#
   using Microsoft.AspNetCore.Builder;
   using Microsoft.AspNetCore.Hosting;
   using Microsoft.Extensions.Hosting;
   using Progress.Sitefinity.AspNetCore;
   using Progress.Sitefinity.AspNetCore.FormWidgets;

   var builder = WebApplication.CreateBuilder(args);

   // Add services to the container.
   builder.Services.AddSitefinity();
   builder.Services.AddViewComponentModels();
   builder.Services.AddFormViewComponentModels();

   var app = builder.Build();

   // Configure the HTTP request pipeline.
   if (app.Environment.IsDevelopment())
   {
       app.UseDeveloperExceptionPage();
   }
   else
   {
       app.UseExceptionHandler("/Error");
       app.UseHsts();
   }

   app.UseStaticFiles();
   app.UseRouting();
   app.UseSitefinity();

   app.UseEndpoints(endpoints =>
   {
       endpoints.MapSitefinityEndpoints();
   });

   app.Run();
   ```
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 should be named *Renderer*.

   > info **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.

### Host Sitefinity CMS on IIS

If your project is hosted on a local IIS, you need to make some specific settings, so that your Sitefinity CMS can communicate with the Renderer application:

1. Download the `Progress.Sitefinity.Cloud.AppGatewayHostRewriteModule` NuGet package manually from [NuGet.org](https://www.nuget.org/).

2. Change the file extension from `.nupkg` to `.zip` and extract the files.

3. In the extracted folder, navigate to the *Content folder*.

4. Copy the `HostRewriteModule.dll` and paste it in a dedicated folder.

   > info  **NOTE**: The built-in Windows `NETWORK SERVICE` account must have permissions to access the folder. The file must remain in this folder for as long as the extension is used. Deleting the file or its folder can cause issues.

5. Open Internet Information Services (IIS) Manager.

6. At the top, select your server and click *Modules*.

7. Click *Configure Native Modules » Register*.

8. Set the name to `AppGatewayHostRewriteModule.`

9. In *Path*, navigate to the *HostRewriteModule.dll*, select it and click *OK*.

10. Ensure the checkbox next to *AppGatewayHostRewriteModule* is selected and click *OK*.

### 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>*

> info **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](https://www.progress.com/documentation/sitefinity-cms/host-the-asp.net-core-rendered-application).

</SfDetails>

<SfDetails summary="Install Sitefinity Next.js Renderer">

In this mode, your Sitefinity frontend can have Next.js pages only. This mode uses the following setup:

<table>
<tbody>
<tr>
<td>

**Types of pages rendered**

</td>
<td>

Next.js

</td>
</tr>
<tr>
<td>

**Backend**

</td>
<td>

Sitefinity CMS\
(<em>running on </em><strong><em>ASP.NET Framework 4.8</em></strong>)

</td>
</tr>
<tr>
<td>

**Frontend**

</td>
<td>

Sitefinity Next.js Renderer\
(running on <strong>Next.js</strong>, rendering Next.js pages)

</td>
</tr>
</tbody>
</table>

> info  **PREREQUISITES**: You must have installed Node.js 22.12 or a newer LTS version.\
> We recommend using version Node.js 22.15.

In this mode, the 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 and the rest can be configured to fallback to the default Sitefinity CMS rendering. For more information, see [Migrate from MVC to Next.js](https://www.progress.com/documentation/sitefinity-cms/migrate-from-mvc-to-next-js) This allows gradual page by page migration from the classic Sitefinity MVC 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.

### Host Sitefinity CMS on IIS

If your project is hosted on a local IIS, you need to make some specific settings, so that your Sitefinity CMS can communicate with the Renderer application:

1. Download the `Progress.Sitefinity.Cloud.AppGatewayHostRewriteModule` NuGet package manually from [NuGet.org](https://www.nuget.org/).
2. Change the file extension from `.nupkg` to `.zip` and extract the files.
3. In the extracted folder, navigate to the *Content folder*.
4. Copy the `HostRewriteModule.dll` and paste it in a dedicated folder.

> info  **NOTE**: The built-in Windows `NETWORK SERVICE` account must have permissions to access the folder. The file must remain in this folder for as long as the extension is used. Deleting the file or its folder can cause issues.

1. Open Internet Information Services (IIS) Manager.
2. At the top, select your server and click *Modules*.
3. Click *Configure Native Modules » Register*.
4. Set the name to `AppGatewayHostRewriteModule.`
5. In *Path*, navigate to the *HostRewriteModule.dll*, select it and click *OK*.
6. Ensure the checkbox next to *AppGatewayHostRewriteModule* is selected and click *OK*.

### 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](https://github.com/Sitefinity/nextjs-samples/tree/main/src/starter-template) 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.

> info  **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 Renderer 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, used to proxy all requests that are not pages and to which all API calls 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. For more information on the secret key, see [Set up the project for local development (using Next.js Renderer)](https://www.progress.com/documentation/sitefinity-cms/cloud-saas/setup-the-project-for-local-development-next-js).
* (Optional) `NEXT_PUBLIC_SF_CMS_URL`: The URL of the CMS for client-side calls, to which all API calls will be made. The default value is `/`.
* (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 frameworks (MVC / Web Forms) so that the requests can be proxied to Sitefinity for rendering. The default value is empty (not set).
* (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. The default value is `false`.
* (Optional) `SF_WHITELISTED_WEBSERVICES`: A comma-separated list of 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`.
* (Optional) `SF_WEBSERVICE_API_KEY`: An access key for the Sitefinity web service (set it in Sitefinity via *Settings » Web Services*). Use it to restrict the web service so that it is accessible only from the Renderer application. If you set it in the renderer, also set it in the web service configuration.

</SfDetails>

## Quick installation procedure (using CLI)

Use the following tutorial to help you quickly install Sitefinity in ASP.NET Core mode:

<SfDetails summary="Install Sitefinity in ASP.NET Core mode">

> info **PREREQUISITES**: You must have:
>
> * installed and set up [Sitefinity CLI](https://github.com/Sitefinity/Sitefinity-CLI).
> * installed and set up [.NET CLI](https://learn.microsoft.com/en-us/dotnet/core/tools/).

### Procedure

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](https://www.progress.com/documentation/sitefinity-cms/run-projects-on-iis) and [Host Sitefinity CMS and the Renderer on the same IIS](https://www.progress.com/documentation/sitefinity-cms/host-sitefinity-cms-and-the-.net-core-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::*`

   > info **NOTE**: Sitefinity CMS comes with an ASP.NET Core template out of the box, which allows you to quickly set up 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 application using Sitefinity CLI by running `sf create "MyRenderer" --renderer` and then update the URL to your Sitefinity CMS project in the `appsettings.json` of your Renderer application.
6. Navigate to the newly created Renderer project folder by running:\
   `cd MyRenderer`
7. Add a widget to your project with the following command:\
   `dotnet new sitefinity-widget --widget-name "YourWidgetName"`
8. Start the ASP.NET Core Renderer using the following command:\
   `dotnet run`

</SfDetails>
