App Deployment

Every JSS application must at some point in its lifecycle transition from disconnected mode, to being deployed to a Sitecore environment. We can use the JSS CLI to deploy our app to Sitecore, which imports all of our disconnected content and components into Sitecore Items that can then be edited.

Once the app is deployed to Sitecore we can use connected mode where we develop the app using live data from Sitecore, as well as integrated mode where the app is rendered by Sitecore and content authors can edit the app's content.

Configuring the Sitecore server to receive the JSS app

In order to host your JSS app the Sitecore server needs to know some configuration about how it will be hosted, such as where to find the site's root item, where to store its templates, what its host name will be, and where to find its JavaScript bundle for server-side rendering.

Step 1. Configure your app's site and host name

Standard example sites used with jss create include a Sitecore site definition in their provided Sitecore configuration patch. Open this configuration patch (sitecore\config\<appname>.config) and confirm the hostName attribute matches a host header that the Sitecore server should respond to with the JSS app. If you are deploying a JSS app that is the default site for the Sitecore installation, you may remove the hostName attribute to respond to any host.

NOTE: When selecting a development hostname, note that Microsoft Edge will not resolve any hostnames without a TLD (i.e. http://sitecore). If you will be testing with Edge, ensure you select a hostname with a TLD (i.e. http://jss.sitecore).

<!-- other attributes removed for brevity -->
<site x:before="site[@name='website']"
      hostName="myapp.siteco.re" />

If you are using a local Sitecore instance, ensure the desired host name is mapped to your localhost via a hosts file entry. On Windows the hosts file can be found at C:\Windows\System32\drivers\etc\hosts (open your editor as administrator to be able to edit it with default security settings).

127.0.0.1    myapp.siteco.re

After adding the host name entry, add it as a binding on your IIS instance as well:

If you are planning on deploying multiple JSS applications, you will need to configure different hosts and host name bindings in IIS in order for Sitecore to resolve the proper site.

Step 2. API Key

The services used by JSS (including the Layout Service, GraphQL, Tracking Service, and Dictionary Service) utilize the API Key mechanism provided by Sitecore Services Client (SSC). You'll need to create an API Key and note its Item ID for use in setting up the sample apps.

Log into Sitecore (e.g. http://myapp.siteco.re/sitecore) and open the Desktop application.
For Sitecore 9.0.x only! Skip for Sitecore 9.1+

Using the database icon in the lower right, switch to the core database. In Sitecore 9.1 and later, the API key is stored in the master database instead, which is the default, so this step is unnecessary.
From the start menu / Sitecore icon, open the Content Editor application.
Navigate to /sitecore/system/Settings/Services/API Keys in the content tree, and via right-click or the Home ribbon, insert a new API Key item. The item can be named anything; the name is for your reference only. Pick something meaningful, e.g. the name of your app.
Set up the fields on the API key:
- CORS Origins: If you will be using connected mode (quite likely), the APIs will need to support CORS so that your dev server (default: http://localhost:3000) is allowed to make HTTP calls to the JSS services. For purely local development setup, use * to allow all origins. In production, only allow specific origins (multiple origins are ;-delimited).
- AllowedControllers: Use the following value. It is also possible to use *, but explicitly whitelisting controllers is a best practice. If you use additional custom SSC API controllers, they would need to be added to this list. Note that GraphQL endpoints require both the GraphQLController to be whitelisted, as well as the GraphQL endpoint URL (with GraphQL:/path/to/endpoint/from/config):
```
  Sitecore.LayoutService.Mvc.Controllers.LayoutServiceController; 
  Sitecore.JavaScriptServices.Globalization.Controllers.DictionaryServiceController; 
  Sitecore.Services.GraphQL.Hosting.Mvc.GraphQLController;
  GraphQL:/api/yourappname
```
- Impersonation User: always specify an explicit user. The impersonation user is a Sitecore user whose security context is used to determine the security rights of the JSS app to Sitecore content. Most apps should use extranet\anonymous, giving them the same security context as any anonymous web user. Note that authenticated users (with valid Sitecore auth cookies) will receive their own security context regardless of this setting; it applies only to anonymous requests.
  
  Do not ever use sitecore\admin or any other privileged user as the impersonation user. A serious security breach will result. Use only extranet\anonymous or a app-specific dedicated user for impersonation.
Save the API key item, publish it (Sitecore 9.1+) and make note of its Item ID (see screenshot below, highlighted). You'll need this ID to connect the JSS app.

The services utilized by JSS will honor the configuration options on the API Key, including Allowed Controllers, CORS Origins, and Impersonation User. See the SSC Documentation for more information on this configuration.

Step 3. Verification

Make a request to the Layout Service on your Sitecore host: http://myapp.siteco.re/sitecore/api/layout/render/jss?item=/&sc_apikey={YOUR_API_KEY_ID}.

Be sure to specify the API key ID created above. If the API key is not provided, the server will return HTTP 400 - Bad Request.

The request should come back with some JSON that looks something like this:

{
  "context": {
    ...
  },
  "route": {
    "name": "Home",
    ...
  }
}

Connecting the JSS app to Sitecore

With Sitecore ready to receive our JSS app, we need to configure the JSS app to deploy to it, and then deploy the app.

Step 1: Setup connection information

To configure the Sitecore connection, run jss setup at a command line within your JSS app, and follow the prompts. You will be asked for several pieces of information:

'Website' folder: This is the root physical path to the Sitecore instance, used to deploy config files and JS build artifacts. File share paths are fine for remote instances. Example: c:\inetpub\wwwroot\MySitecore\Website. If you do not have access to the website folder directly, answer 'no' when asked if your instance is remote.
Sitecore host name. This is the host name of your JSS app (not the Sitecore root host name), which was configured previously. Example: http://jssreactweb
Sitecore import service URL. This is the import service URL of your JSS app, by default it will сonsist of host name of your JSS app plus /sitecore/api/jss/import: http://JssReactWeb/sitecore/api/jss/import. You can left blank value and default value will be set, in another case you can provide your custom URL.
API key ID created above.
Deployment secret. This is a shared secret that enables authentication to deploy your app's items to Sitecore. The setup process can auto-generate a random key, which we recommend. If you choose your own key, the secret must be:
- 32 or more characters long
- Randomly generated

Do not commit the secret to source control; use a unique secret for each environment and limit access to production secrets. For CI environments, jss setup accepts parameters (--help) that can be used to pass the secret and other parameters from variables. By default, the secret is stored in /scjssconfig.json and /sitecore/config/AppName.deploysecret.config - both of which are automatically ignored if you're using Git for source control.

jss setup will generate the /scjssconfig.json file that contains your JSS connection settings.

Deployment tip: To build an environment-agnostic JSS app bundle for production environments that will always use the current hostname for API requests, set the scjssconfig.json's layoutServiceHost setting to blank. This can be useful when you wish to commit one set of build artifacts and deploy them to CM + CD, or even a headless proxy. Note that this technique is incompatible with Connected GraphQL and server-side rendering, which requires an absolute URL to be set.

Step 2: Config deployment

The JSS app is registered with Sitecore using config patches that are deployed to the Sitecore server. When setting up the Sitecore server, we already edited one of these patches when we set the hostName attribute. Before they can take effect on the Sitecore server, we need to deploy them there.

Automatic config deployment (recommended)

Automatic deployment deploys the config patches directly from the JSS app using the JSS CLI. jss setup must have been completed to use this technique.

Open a command prompt/terminal within your JSS app
Run jss deploy config

This will take the Sitecore config patch files under sitecore/config and copy them to the Sitecore App_Config/Include/zzz folder.

This configures the JSS app with Sitecore, creates a site for it, and enables live mode (no need to publish) among other handy things. A Sitecore developer should review the patch file carefully to ensure that all the settings are as they should be; in production, for example, live mode is undesirable.

Ensure that the user account you run the command under has write access to the Sitecore website folder configured in /scjssconfig.json. On Windows, this can also involve UAC elevation.

Manual config deployment

If the JSS app config is to be deployed by a dedicated Sitecore developer (or DevOps), or when you're working with a remote Sitecore instance, the JSS app config may need to be deployed manually. Acquire the sitecore/config/*.config patches from the JSS application, and deploy it to your Sitecore App_Config/Include folder in a location of your liking such as a zzz folder. Ensure you review the config patches for content before deploying them.

Do not commit the <appname>.deploysecret.config patch to source control.

Step 3: App Deployment

Now we are all ready to deploy our JSS app to the Sitecore instance.

3.1: Local Sitecore Instance

If your Sitecore instance is local, or accessible via file share, you can use the CLI for an automated deployment. Skip to 3.2 for a remote instance.

If you are using local self-signed certificate:

Open a command prompt/terminal within your JSS app. If you know certificate value skip to step 4.
Run command using wrong certificate thumbprint jss deploy app --includeContent --includeDictionary --acceptCertificate test
From error message copy certificate thumbprint and paste instead of test
jss deploy app --includeContent --includeDictionary --acceptCertificate CA:CD:3B:DB:19:D1:97:92:F9:80:91:FF:32:CC:F8:35:DC:F5:0B:01

If you are not using local self-signed certificate:

jss deploy app --includeContent --includeDictionary

This will:

Run the production build of your app (by default the build package script)
Generate the app manifest, which defines the Sitecore structure needed to power the app
Generate a JSS manifest package that contains your app manifest and referenced media files
Install the package over HTTP(S) on your Sitecore instance.
Copy build artifacts to the Sitecore website folder

--acceptCertificate parameter whitelists an SSL certificate by thumbprint (certificate pinning). Because Node does not respect Windows trusted root certificates, this enables deploying items to local Sitecore instances that use self-signed certificates without disabling SSL validation entirely.

There are many available options for jss deploy app, which are all set to sensible defaults if unspecified. You can see all of the options for it using jss deploy app --help.

Note that content, media, and dictionary items are not installed by the deployment process by default (which is why we used --includeContent --includeDictionary). It's appropriate to include them as long as disconnected content is being updated but inappropriate if content editors are at work writing content for the app, as they could lose content data. See content workflows for a way to have both coexist.

3.2: Remote Sitecore Instance

For a Sitecore installation that is remote, for example on Azure, you will need to deploy the build artifacts to the Sitecore instance manually.

Open a command prompt/terminal within your JSS app
jss deploy items --includeContent --includeDictionary

This will:
- Generate the app manifest, which defines the Sitecore structure needed to power the app
- Generate a JSS manifest package that contains your app manifest and referenced media files
- Install the package over HTTP(S) on your Sitecore instance
jss build to create production build artifacts
Deploy the build artifacts (from build (React), dist (others)) to the relative path on the Sitecore instance defined in sitecoreDistPath in your package.json file. This is normally something like $sitecore\dist\myappname.

For production setups, this deployment should be automated along with the deployment of other Sitecore artifacts in some sort of automated build process.

Step 4: Verification

Check to make sure your app looks correct in Sitecore by logging in and opening the Content Editor.

1. Content shows up in Content Tree

To test, log into your Sitecore instance using the selected app host http://myapp.siteco.re/sitecore/ and open Content Editor. You should see the app item under /sitecore/content:

2. App is rendered by Sitecore

You should now be able to run the JSS app in integrated mode by visiting the host name that was configured for the site, e.g. http://myapp.siteco.re/. If integrated mode is working correctly, viewing source should reveal a fully rendered app with complete HTML.

3. App is editable in Experience Editor

Try launching the /Home page in Experience Editor. For example, http://myapp.siteco.re/?sc_mode=edit - or launch it from the dashboard:

Now what?

Congratulations, you've successfully deployed your first JSS app! Next we'd recommend diving deeper into some JSS fundamental concepts, starting with JSS Architecture.

Found a problem? Have something to add? Edit this on GitHub