Walkthrough: Deploying a JSS application to Azure

Abstract

Simplified process for deploying JSS applications to a Sitecore instance on Azure

There are many considerations and possible topologies involved in deploying a JSS site to Azure.

This walkthrough describes the simplest way to get up and running with a JSS site using integrated mode in Azure, using a version of Sitecore deployed from the Azure Marketplace.

In production, deployment of the JSS app's build artifacts must be done with an automated build setup leveraging source control, automated builds, testing and file deployment.

For simplicity, in this walkthrough, we use FTPS to deploy our build artifacts.

This walkthrough describes how to:

  • Prepare your Sitecore server on Azure

  • Deploy the application files

Prepare your Sitecore server on Azure

To prepare your Sitecore server on Azure:

  1. Provision Sitecore and Headless Services.

  2. Configure the Sitecore server to accept the JSS application as described for connecting and deploying a JSS application in Sitecore, with the following differences:

    • When in Azure, the configuration deployment step must be performed manually (in production, it should be performed by an automated build step). For example, use an FTPS client to deploy the JSS app configuration from /sitecore/config/* files to the Azure website in the /site/wwwroot/app_config/include folder.

    • The default configuration for the app hostname setting is derived from the app name. For example hostName="jssreactweb". If your JSS app relies on custom hostName settings, you must alter this before deploying to Azure by clearing the hostName setting, making the JSS site the default site, or by setting hostName to something resolvable in DNS and registered to the Custom Domains of the Azure App Service instance. For simplicity, start by clearing the hostName.

    • When deploying the app to Azure, instead of the jss deploy app command, use jss deploy items with the same parameters.

Deploy the application files

The JSS deployment service does not deploy files, you must deploy the files separately to the App Service instance.

To deploy the JSS application files:

Important

This procedure is not necessary for applications built with the Next.js SDK or when using the HTTP Rendering Engine as these do not require execution of your JavaScript bundle on Sitecore platform roles.

  1. From the Azure portal, download your App Service's publishsettings file and locate the FTP connection information. For example:

    <publishProfile profileName="sitecorejss-999-single - FTP" 
      publishUrl="ftp://waws-prod-mwh-015.ftp.azurewebsites.windows.net/site/wwwroot" 
      userName="sitecorejss-999-single\$sitecorejss-999-single" 
      userPWD="long random pw here"...
  2. Using an FTPS client, such as WinSCP, connect to the app service.

  3. Edit the Web.config file. You must select explicit encryption when connecting.

  4. Build your JSS app using jss build, and collect its artifacts.

    • For the React app, artifacts are in the /build directory.

    • For the Angular and Vue apps, artifacts are in the /dist directory.

  5. Collect and deploy the build artifacts of the JSS app using FTPS to the App Service under the relative path listed in the sitecoreDistPath setting configured in the package.json file of your JSS app. For example, /dist/<YourAppName>, translates to deploying the build artifacts to /site/wwwroot/dist/<YourAppName> on the App Service.